致我的儿子布鲁诺，

To my son, Bruno,

两岁时，他为我的生命带来了崭新而耀眼的光芒。当我探索那些将定义我们未来的体系时，我最关心的始终是你即将继承的世界。

who at two years old, brought a new and brilliant light into my life. As I explore the systems that will define our tomorrow, it is the world you will inherit that is foremost in my thoughts.

致我的儿子莱昂纳多和洛伦佐，以及我的女儿奥罗拉：

To my sons, Leonardo and Lorenzo, and my daughter Aurora,

我为你们所成为的优秀女性和男性以及你们正在创造的美好世界感到无比自豪。

My heart is filled with pride for the women and men you have become and the wonderful world you are building.

本书讲述的是如何构建智能工具，但更饱含着对你们这一代人以智慧和慈悲之心引领这些工具的深切期盼。如果我们学会运用这些强大的技术服务于人类，推动人类进步，那么无论对你们还是对我们所有人来说，未来都将无比光明。

This book is about how to build intelligent tools, but it is dedicated to the profound hope that your generation will guide them with wisdom and compassion. The future is incredibly bright, for you and for us all, if we learn to use these powerful technologies to serve humanity and help it progress.

我满怀爱意。

With all my love.

致谢

Acknowledgment

我衷心感谢所有为本书的出版做出贡献的个人和团队。

I would like to express my sincere gratitude to the many individuals and teams who made this book possible.

首先，我要感谢谷歌坚持其使命，赋予谷歌员工权力，并尊重创新的机会。

First and foremost, I thank Google for adhering to its mission, empowering Googlers, and respecting the opportunity to innovate.

我感谢首席技术官办公室给予我探索新领域的机会，感谢其秉持“实用魔法”的使命，以及适应新出现的机遇的能力。

I am grateful to the Office of the CTO for giving me the opportunity to explore new areas, for adhering to its mission of "practical magic," and for its capacity to adapt to new emerging opportunities.

我衷心感谢副总裁威尔·格兰尼斯（Will Grannis），感谢他对员工的信任和以身作则的领导风格。感谢我的经理约翰·阿贝尔（John Abel），感谢他鼓励我开展各项工作，并始终以他敏锐的英式思维给予我指导。 感谢安托万·拉曼贾特（Antoine Larmanjat）在代码层面开发LLM方面的工作，感谢王汉汉（Hann Hann Wang）参与的关于智能体的讨论，以及黄英超（Yingchao Huang）对时间序列的深刻见解。 感谢阿什温·拉姆（Ashwin Ram）的领导，感谢玛西·马斯卡罗（Massy Mascaro）的启发性工作，感谢詹妮弗·贝内特（Jennifer Bennett）的技术专长，感谢布雷特·斯拉特金（Brett Slatkin）的工程贡献，以及埃里克·申（Eric Sc​​hen）的启发性讨论。OCTO团队，特别是斯科特·彭伯西（Scott Penberthy），值得表扬。最后，衷心感谢帕特里夏·弗洛里西（Patricia Florissi）对智能体社会影响的远见卓识。     

I would like to extend my heartfelt thanks to Will Grannis, our VP, for the trust he puts in people and for being a servant leader. To John Abel, my manager, for encouraging me to pursue my activities and for always providing great guidance with his British acumen. I extend my gratitude to Antoine Larmanjat for our work on LLMs in code, Hann Hann Wang for agent discussions, and Yingchao Huang for time series insights.   Thanks to Ashwin Ram for leadership, Massy Mascaro for inspiring work, Jennifer Bennett for technical expertise, Brett Slatkin for engineering, and Eric Schen for stimulating discussions.   The OCTO team, especially Scott Penberthy, deserves recognition.   Finally, deep appreciation to Patricia Florissi for her inspiring vision of Agents' societal impact.

我还要感谢 Marco Argenti，他提出了富有挑战性和激励性的愿景，即利用经纪人来增强人力资源。同时，我也要感谢 Jim Lanzone 和 Jordi Ribas，他们不断提升搜索领域和经纪人领域之间的关系。

My appreciation also goes to Marco Argenti for the challenging and motivating vision of agents augmenting the human workforce. My thanks also go to Jim Lanzone and Jordi Ribas for pushing the bar on the relationship between the world of Search and the world of Agents.

我还要感谢云端人工智能团队，特别是他们的领导 Saurabh Tiwary，感谢他带领人工智能组织朝着有原则的方向发展。感谢区域技术负责人 Salem Haykal，他是一位鼓舞人心的同事。感谢 Google Agentspace 的联合创始人 Vladimir Vuskovic，感谢 Kate (Katarzyna) Olszewska 在 Kaggle Game Arena 上的 Agentic 合作，感谢 Nate Keating 对 Kaggle 的热情投入，Kaggle 社区为人工智能做出了巨大贡献。还要感谢 Kamelia Aryafa，她领导着专注于 Agentspace 和 Enterprise NotebookLM 的应用人工智能和机器学习团队；以及 Jahn Wooland，他是一位真正以交付成果为导向的领导者，也是一位随时提供建议的挚友。

I am also indebted to the Cloud AI teams, especially their leader Saurabh Tiwary, for driving the AI organization towards principled progress. Thank you to Salem Salem Haykal, the Area Technical Leader, for being an inspiring colleague. My thanks to Vladimir Vuskovic, co-founder of Google Agentspace, Kate (Katarzyna) Olszewska for our Agentic collaboration on Kaggle Game Arena, and Nate Keating for driving Kaggle with passion, a community that has given so much to AI. My thanks also to Kamelia Aryafa, leading applied AI and ML teams focused on Agentspace and Enterprise NotebookLM, and to Jahn Wooland, a true leader focused on delivering and a personal friend always there to provide advice.

特别感谢黄英超，他是一位才华横溢的人工智能工程师，前途无量；感谢王瀚，他激励我重拾对智能体的兴趣（我最初对智能体感兴趣是在 1994 年）；还要感谢 Lee Boonstra 在提示工程方面做出的杰出贡献。

A special thanks to Yingchao Huang for being a brilliant AI engineer with a great career in front of you, Hann Wang for challenging me to return to my interest in Agents after an initial interest in 1994, and to Lee Boonstra for your amazing work on prompt engineering.

我还要感谢 GenAI 五日活动团队，包括副总裁 Alison Wagonfeld 对团队的信任，Anant Nawalgaria 一如既往的出色表现，以及 Paige Bailey 的积极态度和领导才能。

My thanks also go to the 5 Days of GenAI team, including our VP Alison Wagonfeld for the trust put in the team, Anant Nawalgaria for always delivering, and Paige Bailey for her can-do attitude and leadership.

我还要衷心感谢 Mike Styer、Turan Bulmus 和 Kanchana Patlolla  ，感谢他们帮助我在 2025 年 Google I/O 大会上发布了三个 Agent。感谢你们的辛勤付出。

I am also deeply grateful to Mike Styer, Turan Bulmus, and Kanchana Patlolla  for helping me ship three Agents at Google I/O 2025. Thank you for your immense work.

我衷心感谢 Thomas Kurian 在推动云计算和人工智能项目方面展现出的坚定领导力、热情和信任。 我也由衷感谢 Emanuel Taropa，他积极乐观、勇于担当的态度使他成为我在谷歌遇到的最杰出的同事，为我树立了深刻的榜样。最后，感谢 Fiona Cicconi 与我进行的关于谷歌的精彩讨论。   

I want to express my sincere gratitude to Thomas Kurian for his unwavering leadership, passion, and trust in driving the Cloud and AI initiatives.   I also deeply appreciate Emanuel Taropa, whose inspiring "can-do" attitude made him the most exceptional colleague I've encountered at Google, setting a truly profound example.   Finally, thanks to Fiona Cicconi for our engaging discussions about Google.

我衷心感谢 Demis Hassabis、Pushmeet Kohli 以及整个 GDM 团队，感谢他们为开发 Gemini、AlphaFold、AlphaGo 和 AlphaGenome 等项目所付出的热情努力，以及他们为推动科学进步、造福社会所做出的贡献。 特别感谢 Yossi Matias 对 Google Research 的领导，以及他一直以来提供的宝贵建议。我从您身上学到了很多。   

I extend my gratitude to Demis Hassabis, Pushmeet Kohli, and the entire GDM team for their passionate efforts in developing Gemini, AlphaFold, AlphaGo, and AlphaGenome, among other projects, and for their contributions to advancing science for the benefit of society.   A special thank you to Yossi Matias for his leadership of Google Research and for consistently offering invaluable advice.   I have learned a great deal from you.

特别感谢帕蒂·梅斯，她在90年代率先提出了软件代理的概念，并始终致力于研究计算机系统和数字设备如何增强人类能力，帮助他们解决记忆、学习、决策、健康和福祉等方面的问题。您在91年的愿景如今已成为现实。

A special thanks to Patti Maes, who pioneered the concept of Software Agents in the 90s and remains focused on the question of how computer systems and digital devices might augment people and assist them with issues such as memory, learning, decision making, health, and wellbeing. Your vision back in '91 became a reality today.

我还要感谢保罗·德鲁加斯和施普林格出版社的所有出版团队成员，感谢他们让这本书得以出版。

I also want to extend my gratitude to Paul Drougas and all the Publisher team at Springer for making this book possible.

我衷心感谢众多才华横溢的人士，是他们的帮助才成就了这本书的诞生。我由衷地感谢 Marco Fago 的巨大贡献，他不仅编写了代码和图表，还审阅了全文。我也感谢 Mahtab Syed 的编码工作，以及 Ankita Guha 对众多章节提出的极其详尽的反馈。Priya Saxena 的精辟修改、Jae Lee 的细致审阅，以及 Mario da Roza 为创建 NotebookLM 版本所做的辛勤工作，都极大地提升了本书的质量。我非常幸运地拥有一支专家审阅团队，他们为本书的最初章节提供了宝贵的意见，在此我感谢 Amita Kapoor 博士、Fatma Tarlaci 博士、Alessandro Cornacchia 博士和 Aditya Mandlekar 的专业知识。此外，我还要真诚地感谢 Ashley Miller、A Amir John 和 Palak Kamdar (Vasani) 的独特贡献。最后，衷心感谢 Rajat Jain、Aldo Pahor、Gaurav Verma、Pavithra Sainath、Mariusz Koczwara、Abhijit Kumar、Armstrong Foundjem、Haiming Ran、Udita Patel 和 Kaurnakar Kotha。

I am deeply indebted to the many talented people who helped bring this book to life. My heartfelt thanks go to Marco Fago for his immense contributions, from code and diagrams to reviewing the entire text. I’m also grateful to Mahtab Syed for his coding work and to Ankita Guha for her incredibly detailed feedback on so many chapters. The book was significantly improved by the insightful amendments from Priya Saxena, the careful reviews from Jae Lee, and the dedicated work of Mario da Roza in creating the NotebookLM version. I was fortunate to have a team of expert reviewers for the initial chapters, and I thank Dr. Amita Kapoor, Fatma Tarlaci, PhD, Dr. Alessandro Cornacchia, and Aditya Mandlekar for lending their expertise. My sincere appreciation also goes to Ashley Miller, A Amir John, and Palak Kamdar (Vasani) for their unique contributions. For their steadfast support and encouragement, a final, warm thank you is due to Rajat Jain, Aldo Pahor, Gaurav Verma, Pavithra Sainath, Mariusz Koczwara, Abhijit Kumar, Armstrong Foundjem, Haiming Ran, Udita Patel, and Kaurnakar Kotha.

如果没有你，这个项目根本不可能完成。所有的功劳都归功于你，所有的错误都由我承担。

This project truly would not have been possible without you. All the credit goes to you, and all the mistakes are mine.

我的所有版税都捐给了救助儿童会。

All my royalties are donated to Save the Children.

前言

Foreword

人工智能领域正处于一个激动人心的转折点。我们正在超越构建能够简单处理信息的模型，转向创建能够推理、规划和行动的智能系统，以完成具有模糊性任务的复杂目标。正如本书恰如其分地描述的那样，这些“智能体”系统代表了人工智能的下一个前沿领域，它们的开发对于谷歌而言既是一项挑战，也令我们感到兴奋和鼓舞。

The field of artificial intelligence is at a fascinating inflection point. We are moving beyond building models that can simply process information to creating intelligent systems that can reason, plan, and act to achieve complex goals with ambiguous tasks. These "agentic" systems, as this book so aptly describes them, represent the next frontier in AI, and their development is a challenge that excites and inspires us at Google.

《智能体设计模式：构建智能系统的实战指南》的出版恰逢其时，为我们开启这段旅程提供了完美的指引。本书一针见血地指出，大型语言模型（即智能体的认知引擎）的强大功能必须通过结构化和周密的设计来驾驭。正如设计模式通过提供通用语言和可复用的解决方案革新了软件工程一样，本书中的智能体模式也将成为构建健壮、可扩展且可靠的智能系统的基础。

"Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems" arrives at the perfect moment to guide us on this journey. The book rightly points out that the power of large language models, the cognitive engines of these agents, must be harnessed with structure and thoughtful design. Just as design patterns revolutionized software engineering by providing a common language and reusable solutions to common problems, the agentic patterns in this book will be foundational for building robust, scalable, and reliable intelligent systems.

用“画布”来比喻构建智能体系统，与我们在谷歌Vertex AI平台上的工作理念不谋而合。我们致力于为开发者提供最强大、最灵活的画布，助力他们构建下一代人工智能应用。本书提供实用且易于操作的指导，帮助开发者充分发挥这块画布的潜力。本书探讨了从提示链和工具使用到智能体间协作、自我纠错、安全性和防护机制等各种模式，为希望构建复杂人工智能智能体的开发者提供了一套全面的工具包。

The metaphor of a "canvas" for building agentic systems is one that resonates deeply with our work on Google's Vertex AI platform. We strive to provide developers with the most powerful and flexible canvas on which to build the next generation of AI applications. This book provides the practical, hands-on guidance that will empower developers to use that canvas to its full potential. By exploring patterns from prompt chaining and tool use to agent-to-agent collaboration, self-correction, safety and guardrails, this book offers a comprehensive toolkit for any developer looking to build sophisticated AI agents.

人工智能的未来将取决于能够构建这些智能系统的开发者的创造力和独创性。《智能体设计模式》是一本不可或缺的资源，它将帮助激发这种创造力。本书不仅提供了理解智能体系统的“是什么”和“为什么”，还提供了理解其“如何做”所需的基本知识和实践案例。

The future of AI will be defined by the creativity and ingenuity of developers who can build these intelligent systems. "Agentic Design Patterns" is an indispensable resource that will help to unlock that creativity. It provides the essential knowledge and practical examples to not only understand the "what" and "why" of agentic systems, but also the "how."

我很高兴看到这本书来到开发者社区。书中阐述的模式和原则无疑将加速开发创新且具有深远影响的人工智能应用，这些应用将在未来数年内塑造我们的世界。

I am thrilled to see this book in the hands of the developer community. The patterns and principles within these pages will undoubtedly accelerate the development of innovative and impactful AI applications that will shape our world for years to come.

索拉布·蒂瓦里

Saurabh Tiwary

谷歌云人工智能副总裁兼总经理

VP & General Manager, CloudAI @ Google

一位思想领袖的视角 ：权力与责任

A Thought Leader's Perspective : Power and Responsibility

在过去四十年里，我见证了无数的技术周期——从个人电脑和互联网的诞生，到移动和云计算的革命——但没有一个周期像这一次一样。多年来，围绕人工智能的讨论一直遵循着炒作与幻灭的熟悉节奏，所谓的“人工智能夏季”之后便是漫长而寒冷的冬季。但这一次，情况有所不同。讨论的焦点已经发生了明显的转变。如果说过去的十八个月是

Of all the technology cycles I’ve witnessed over the past four decades—from the birth of the personal computer and the web, to the revolutions in mobile and cloud—none has felt quite like this one. For years, the discourse around Artificial Intelligence was a familiar rhythm of hype and disillusionment, the so-called “AI summers” followed by long, cold winters. But this time, something is different. The conversation has palpably shifted. If the last eighteen months were

关于引擎——大型语言模型（LLM）令人叹为观止、近乎垂直的崛起——下一个时代将关乎我们围绕它构建的“汽车”。它将关乎驾驭这种原始力量的框架，将其从生成看似合理的文本的工具转变为真正的行动主体。

about the engine—the breathtaking, almost vertical ascent of Large Language Models (LLMs)—the next era will be about the car we build around it. It will be about the frameworks that harness this raw power, transforming it from a generator of plausible text into a true agent of action.

我承认，我一开始是个怀疑论者。我发现，可信度往往与一个人对某个主题的了解程度成反比。早期的模型虽然流畅，但感觉就像患有某种冒名顶替综合症，它们追求的是可信度而非正确性。但随后出现了转折点，一种新型“推理”模型带来了质的飞跃。突然间，我们不再只是在与一台预测序列中下一个词的统计机器对话；

I admit, I began as a skeptic. Plausibility, I’ve found, is often inversely proportional to one’s own knowledge of a subject. Early models, for all their fluency, felt like they were operating with a kind of impostor syndrome, optimized for credibility over correctness. But then came the inflection point, a step-change brought about by a new class of "reasoning" models. Suddenly, we weren't just conversing with a statistical machine that predicted the next word in a sequence;

我们得以窥见一种萌芽状态的认知。

we were getting a peek into a nascent form of cognition.

第一次尝试使用这种新型智能编码工具时，我感受到了那种熟悉的魔力。我把它交给它处理一个我一直没时间做的个人项目：将一个慈善机构的网站从一个简单的网页构建器迁移到一个完善的、现代化的 CI/CD 环境。接下来的二十分钟里，它开始工作，提出澄清问题，请求凭据，并提供状态更新。感觉不像是在使用工具，而更像是在与一位初级开发人员协作。当它向我交付一个完全可部署的软件包，并附带完善的文档和单元测试时，我简直惊呆了。

The first time I experimented with one of the new agentic coding tools, I felt that familiar spark of magic. I tasked it with a personal project I’d never found the time for: migrating a charity website from a simple web builder to a proper, modern CI/CD environment. For the next twenty minutes, it went to work, asking clarifying questions, requesting credentials, and providing status updates. It felt less like using a tool and more like collaborating with a junior developer. When it presented me with a fully deployable package, complete with impeccable documentation and unit tests, I was floored.

当然，它并不完美。它会犯错，也会遇到瓶颈。它需要我的监督，更重要的是，需要我的判断才能让它重回正轨。这次经历让我深刻体会到，在我漫长的职业生涯中，我曾无数次痛苦地领悟到：盲目信任是行不通的。然而，这个过程却令人着迷。窥探它的“思维链”就像观看一个大脑的运作——混乱、非线性，充满了启动、停止和自我修正，与我们人类的推理过程颇为相似。它并非一条直线，而是一次通往解决方案的随机漫步。这其中蕴藏着某种新事物的雏形：它不仅是一种能够生成内容的智能，更是一种能够生成计划的 智能 。

Of course, it wasn't perfect. It made mistakes. It got stuck. It required my supervision and, crucially, my judgment to steer it back on course. The experience drove home a lesson I’ve learned the hard way over a long career: you cannot afford to trust blindly. Yet, the process was fascinating. Peeking into its "chain of thought" was like watching a mind at work—messy, non-linear, full of starts, stops, and self-corrections, not unlike our own human reasoning. It wasn’t a straight line; it was a random walk toward a solution. Here was the kernel of something new: not just an intelligence that could generate content, but one that could generate a plan .

这就是智能体框架的优势所在。它就像静态的地铁线路图和能够实时重新规划路线的动态GPS之间的区别。传统的基于规则的自动机遵循固定路径；一旦遇到意外障碍，它就会崩溃。而由推理模型驱动的人工智能智能体则具备观察、适应和寻找其他路径的潜力。它拥有某种数字常识，使其能够应对现实中无数的极端情况。这标志着一种转变：不再仅仅是告诉计算机做 什么  ，而是解释我们 为什么  需要做某件事，并信任它能够找到实现 方法 。

This is the promise of agentic frameworks. It’s the difference between a static subway map and a dynamic GPS that reroutes you in real-time. A classic rules-based automaton follows a fixed path; when it encounters an unexpected obstacle, it breaks. An AI agent, powered by a reasoning model, has the potential to observe, adapt, and find another way. It possesses a form of digital common sense that allows it to navigate the countless edge cases of reality. It represents a shift from simply telling a computer what  to do, to explaining why  we need something done and trusting it to figure out the how .

尽管这片新领域令人兴奋，但也带来了一份沉甸甸的责任感，尤其对我这个全球金融机构的首席信息官而言更是如此。风险极其巨大。一个代理人在制作“鸡肉三文鱼融合派”的食谱时出错，或许只是个有趣的轶事。但如果代理人在执行交易、管理风险或处理客户数据时出错，那就成了真正的问题。我读过相关的免责声明和警示案例：比如，一个网络自动化代理在登录失败后，竟然给一位议员发邮件抱怨登录障碍。这则略带黑色幽默的案例提醒我们，我们正在面对一项我们尚未完全了解的技术。

As exhilarating as this new frontier is, it brings a profound sense of responsibility, particularly from my vantage point as the CIO of a global financial institution. The stakes are immeasurably high. An agent that makes a mistake while creating a recipe for a "Chicken Salmon Fusion Pie" is a fun anecdote. An agent that makes a mistake while executing a trade, managing risk, or handling client data is a real problem. I’ve read the disclaimers and the cautionary tales: the web automation agent that, after failing a login, decided to email a member of parliament to complain about login walls. It’s a darkly humorous reminder that we are dealing with a technology we don’t fully understand.

在这里，精湛的工艺、深厚的文化底蕴以及对原则的不懈坚持，成为我们不可或缺的指导。我们的工程准则并非纸上谈兵，而是我们的指路明灯。我们必须 以目标为导向进行构建 ，确保我们设计的每一个代理都基于对客户问题的清晰理解。我们必须 未雨绸缪 ，预见潜在的故障模式，并从设计之初就赋予系统强大的韧性。最重要的是，我们必须 赢得信任 ，公开透明地展示我们的方法，并对最终结果负责。

This is where craft, culture, and a relentless focus on our principles become our essential guide. Our Engineering Tenets are not just words on a page; they are our compass. We must Build with Purpose , ensuring that every agent we design starts from a clear understanding of the client problem we are solving. We must Look Around Corners , anticipating failure modes and designing systems that are resilient by design. And above all, we must Inspire Trust , by being transparent about our methods and accountable for our outcomes.

在一个智能体主导的世界里，这些原则显得尤为紧迫。残酷的现实是，你不能简单地将这些强大的新工具叠加到混乱、不一致的系统中，就指望获得良好的结果。混乱的系统加上智能体，注定会酿成灾难。用“垃圾”数据训练的人工智能不仅会产生垃圾结果，还会产生看似合理、充满自信的垃圾结果，从而毒害整个流程。因此，我们首要且至关重要的任务是做好准备。我们必须投资于干净的数据、一致的元数据和定义完善的API。我们必须构建现代化的“州际系统”，使这些智能体能够安全、高速地运行。这才是难点所在。

In an agentic world, these tenets take on new urgency. The hard truth is that you cannot simply overlay these powerful new tools onto messy, inconsistent systems and expect good results. Messy systems plus agents are a recipe for disaster. An AI trained on "garbage" data doesn’t just produce garbage-out; it produces plausible, confident garbage that can poison an entire process. Therefore, our first and most critical task is to prepare the ground. We must invest in clean data, consistent metadata, and well-defined APIs. We have to build the modern "interstate system" that allows these agents to operate safely and at high velocity. It is the hard,

构建可编程企业的基础性工作，即“企业即软件”，其中我们的流程与我们的代码一样架构完善。

foundational work of building a programmable enterprise, an "enterprise as software," where our processes are as well-architected as our code.

归根结底，这段旅程并非要取代人类的创造力，而是要增强它。它要求我们所有人掌握一系列新的技能：清晰地阐述任务的能力、明智的授权技巧以及认真核实成果质量的严谨态度。它要求我们保持谦逊，承认自身的不足，并永不止步地学习。本书接下来的内容将提供构建这些新框架的技术路线图。我希望​​你们不仅能运用这些技术构建可能实现的框架，更能构建正确、稳健且负责任的框架。

Ultimately, this journey is not about replacing human ingenuity, but about augmenting it. It demands a new set of skills from all of us: the ability to explain a task with clarity, the wisdom to delegate, and the diligence to verify the quality of the output. It requires us to be humble, to acknowledge what we don’t know, and to never stop learning. The pages that follow in this book offer a technical map for building these new frameworks. My hope is that you will use them not just to build what is possible, but to build what is right, what is robust, and what is responsible.

世界呼吁每一位工程师挺身而出。我相信我们已经准备好迎接挑战。

The world is asking every engineer to step up. I am confident we are ready for the challenge.

享受旅程。

Enjoy the journey.

Marco Argenti，高盛首席信息官

Marco Argenti, CIO, Goldman Sachs

前言

Preface

欢迎阅读《智能体设计模式：构建智能系统的实战指南》。纵观现代人工智能的发展历程，我们可以看到一个清晰的演进过程：从简单的被动程序，发展到能够理解上下文、做出决策并与环境和其他系统动态交互的复杂自主实体。这些就是智能体以及它们所构成的智能体系统。

Welcome to "Agentic Design Patterns: A Hands-On Guide to Building Intelligent Systems." As we look across the landscape of modern artificial intelligence, we see a clear evolution from simple, reactive programs to sophisticated, autonomous entities capable of understanding context, making decisions, and interacting dynamically with their environment and other systems. These are the intelligent agents and the agentic systems they comprise.

强大的大型语言模型（LLM）的出现，为理解和生成类人内容（例如文本和媒体）提供了前所未有的能力，并成为许多智能体的认知引擎。然而，要将这些能力整合到能够可靠地实现复杂目标的系统中，需要的不仅仅是一个强大的模型。它还需要结构、设计，以及对智能体如何感知、计划、行动和交互的深思熟虑的方法。

The advent of powerful large language models (LLMs) has provided unprecedented capabilities for understanding and generating human-like content such as text and media, serving as the cognitive engine for many of these agents. However, orchestrating these capabilities into systems that can reliably achieve complex goals requires more than just a powerful model. It requires structure, design, and a thoughtful approach to how the agent perceives, plans, acts, and interacts.

把构建智能系统想象成在画布上创作一件复杂的艺术作品或工程作品。这块画布并非空白的视觉空间，而是为智能体提供生存和运行环境及工具的底层基础设施和框架。它是你构建智能应用程序的基础，用于管理状态、通信、工具访问和逻辑流程。

Think of building intelligent systems as creating a complex work of art or engineering on a canvas. This canvas isn't a blank visual space, but rather the underlying infrastructure and frameworks that provide the environment and tools for your agents to exist and operate. It's the foundation upon which you'll build your intelligent application, managing state, communication, tool access, and the flow of logic.

在这个智能体画布上进行有效构建，需要的不仅仅是简单地将组件拼凑在一起。它需要理解已被验证有效的技术—— 模式  ——来应对设计和实现智能体行为时常见的挑战。正如建筑模式指导建筑物的建造，设计模式构建软件结构一样，智能体设计模式为你在所选画布上实现智能体时遇到的反复出现的问题提供了可重用的解决方案。

Building effectively on this agentic canvas demands more than just throwing components together. It requires understanding proven techniques – patterns  – that address common challenges in designing and implementing agent behavior. Just as architectural patterns guide the construction of a building, or design patterns structure software, agentic design patterns provide reusable solutions for the recurring problems you'll face when bringing intelligent agents to life on your chosen canvas.

什么是智能体系统？

What are Agentic Systems?

从本质上讲，智能体系统是一种计算实体，它能够感知其环境（包括数字环境和潜在的物理环境），基于这些感知以及一组预定义或学习到的目标做出明智的决策，并自主执行行动以实现这些目标。与遵循僵化、循序渐进指令的传统软件不同，智能体展现出一定程度的灵活性和主动性。

At its core, an agentic system is a computational entity designed to perceive its environment (both digital and potentially physical), make informed decisions based on those perceptions and a set of predefined or learned goals, and execute actions to achieve those goals autonomously. Unlike traditional software, which follows rigid, step-by-step instructions, agents exhibit a degree of flexibility and initiative.

假设你需要一个系统来管理客户咨询。传统的系统可能遵循固定的脚本。然而，智能体系统能够感知客户咨询的细微差别，访问知识库，与其他内部系统（例如订单管理系统）交互，可能会提出澄清问题，并主动解决问题，甚至可能预测未来的需求。这些智能体在你的应用程序基础设施上运行，利用可用的服务和数据。

Imagine you need a system to manage customer inquiries. A traditional system might follow a fixed script. An agentic system, however, could perceive the nuances of a customer's query, access knowledge bases, interact with other internal systems (like order management), potentially ask clarifying questions, and proactively resolve the issue, perhaps even anticipating future needs. These agents operate on the canvas of your application's infrastructure, utilizing the services and data available to them.

智能体系统通常具有自主性、主动性和反应性等特征。 自主性 使它们能够在无需持续人工监督的情况下行动； 主动性 使它们能够主动采取行动以实现目标； 反应性 使它们能够有效地应对环境变化。它们本质上是 目标导向的 ，不断朝着目标努力。 工具使用能力是智能体系统的关键能力 ，使它们能够与外部应用程序接口（API）、数据库或服务进行交互，从而有效地拓​​展其自身所处环境之外的功能。它们拥有 记忆功能，能够在交互过程中保留信息，并且可以  与用户、其他系统，甚至在同一或相连的平台上运行的其他智能体进行 通信。

Agentic systems are often characterized by features like autonomy , allowing them to act without constant human oversight; proactiveness , initiating actions towards their goals; and reactiveness , responding effectively to changes in their environment. They are fundamentally goal-oriented , constantly working towards objectives. A critical capability is tool use , enabling them to interact with external APIs, databases, or services – effectively reaching out beyond their immediate canvas. They possess memory , retain information across interactions, and can engage in communication  with users, other systems, or even other agents operating on the same or connected canvases.

有效实现这些特性会带来显著的复杂性。智能体如何在画布上的多个步骤中保持状态？它如何决定 何时  以及 如何  使用工具？不同智能体之间的通信如何管理？如何构建系统的弹性以应对意外结果或错误？

Effectively realizing these characteristics introduces significant complexity. How does the agent maintain state across multiple steps on its canvas? How does it decide when  and how  to use a tool? How is communication between different agents managed? How do you build resilience into the system to handle unexpected outcomes or errors?

为什么模式在智能体开发中至关重要

Why Patterns Matter in Agent Development

正是这种复杂性使得智能体设计模式不可或缺。它们并非僵化的规则，而是经过实战检验的模板或蓝图，为智能体领域中常见的设计和实现挑战提供了行之有效的解决方案。通过识别和应用这些设计模式，您可以获得能够提升您在画布上构建的智能体的结构、可维护性、可靠性和效率的解决方案。

This complexity is precisely why agentic design patterns are indispensable. They are not rigid rules, but rather battle-tested templates or blueprints that offer proven approaches to standard design and implementation challenges in the agentic domain. By recognizing and applying these design patterns, you gain access to solutions that enhance the structure, maintainability, reliability, and efficiency of the agents you build on your canvas.

使用设计模式可以帮助您避免重复发明诸如管理对话流程、集成外部功能或协调多个代理操作等基本解决方案。它们提供了一种通用语言和结构，使您的代理逻辑更清晰，更易于他人（以及您自己）理解和维护。实施专为错误处理或状态管理而设计的模式，有助于构建更健壮、更可靠的系统。利用这些成熟的方法可以加快您的开发流程，使您能够专注于应用程序的独特方面，而不是代理行为的基础机制。

Using design patterns helps you avoid reinventing fundamental solutions for tasks like managing conversational flow, integrating external capabilities, or coordinating multiple agent actions. They provide a common language and structure that makes your agent's logic clearer and easier for others (and yourself in the future) to understand and maintain. Implementing patterns designed for error handling or state management directly contributes to building more robust and reliable systems. Leveraging these established approaches accelerates your development process, allowing you to focus on the unique aspects of your application rather than the foundational mechanics of agent behavior.

本书提炼出21种关键设计模式，这些模式代表了在各种技术平台上构建复杂智能体的基本构建模块和技巧。理解并应用这些模式将显著提升您高效设计和实现智能系统的能力。

This book extracts 21 key design patterns that represent fundamental building blocks and techniques for constructing sophisticated agents on various technical canvases. Understanding and applying these patterns will significantly elevate your ability to design and implement intelligent systems effectively.

本书概述及使用方法

Overview of the Book and How to Use It

本书《 智能体设计模式 ：构建智能系统的实战指南》旨在成为一本实用且易于理解的参考书。本书主要侧重于清晰地解释每一种智能体模式，并提供具体、可运行的代码示例来演示其实现方式。全书共21章，涵盖了从结构化顺序操作（提示链）和外部交互（工具使用）等基础概念到协作工作（多智能体协作）和自我改进（自我纠正）等更高级主题的各种设计模式。

This book, " Agentic Design Patterns : A Hands-On Guide to Building Intelligent Systems," is crafted to be a practical and accessible resource. Its primary focus is on clearly explaining each agentic pattern and providing concrete, runnable code examples to demonstrate its implementation. Across 21 dedicated chapters, we will explore a diverse range of design patterns, from foundational concepts like structuring sequential operations (Prompt Chaining) and external interaction (Tool Use) to more advanced topics like collaborative work (Multi-Agent Collaboration) and self-improvement (Self-Correction).

本书按章节组织，每章深入探讨一种主体模式。每章内容包括：

The book is organized chapter by chapter, with each chapter delving into a single agentic pattern. Within each chapter, you will find:

• 详细的 模式概述，  清晰地解释了该模式及其在智能设计中的作用。
• A detailed Pattern Overview  providing a clear explanation of the pattern and its role in agentic design.
• 实际应用与用例 部分 ，阐述了该模式在现实世界中的价值以及它带来的好处。
• A section on Practical Applications & Use Cases  illustrating real-world scenarios where the pattern is invaluable and the benefits it brings.
• 本示例提供了 一个 实用的代码示例，其中包含可运行的实用代码，演示了如何使用主流的代理开发框架来实现该模式。您将在此了解如何在技术画布的上下文中应用该模式。
• A Hands-On Code Example  offering practical, runnable code that demonstrates the pattern's implementation using prominent agent development frameworks. This is where you'll see how to apply the pattern within the context of a technical canvas.
• 要点总结，  概括最重要的几点，方便快速回顾。
• Key Takeaways  summarizing the most crucial points for quick review.
• 提供进一步探索的参考资料  ，为深入学习该模式及相关概念提供资源。
• References  for further exploration, providing resources for deeper learning on the pattern and related concepts.

本书各章节的编排顺序旨在循序渐进地构建概念，但您也可以将其作为参考资料，直接跳转到解决您在智能体开发项目中遇到的具体挑战的章节。附录全面介绍了高级提示技术、在真实环境中应用人工智能智能体的原则，以及基本的智能体框架概述。此外，本书还包含实用的在线教程，提供使用 AgentSpace 等特定平台以及命令行界面构建智能体的分步指导。本书始终强调实际应用；我们强烈建议您运行代码示例，进行实验，并根据您选择的平台进行调整，从而构建您自己的智能系统。

While the chapters are ordered to build concepts progressively, feel free to use the book as a reference, jumping to chapters that address specific challenges you face in your own agent development projects. The appendices provide a comprehensive look at advanced prompting techniques, principles for applying AI agents in real-world environments, and an overview of essential agentic frameworks. To complement this, practical online-only tutorials are included, offering step-by-step guidance on building agents with specific platforms like AgentSpace and for the command-line interface. The emphasis throughout is on practical application; we strongly encourage you to run the code examples, experiment with them, and adapt them to build your own intelligent systems on your chosen canvas.

我经常听到一个很好的问题：“人工智能发展如此迅速，为什么还要写一本可能很快就会过时的书呢？”我的初衷恰恰相反。正因为事物发展如此迅速，我们才更需要停下来，找出那些正在逐渐成型的基本原理。像红绿灯（RAG）、反射、路由、内存以及我在书中讨论的其他模式，正在成为构建人工智能的基本模块。这本书旨在邀请读者反思这些核心理念，它们为我们构建人工智能提供了基础。人类需要这些对基础模式的反思时刻。

A great question I hear is, 'With AI changing so fast, why write a book that could be quickly outdated?' My motivation was actually the opposite. It's precisely because things are moving so quickly that we need to step back and identify the underlying principles that are solidifying. Patterns like RAG, Reflection, Routing, Memory and the others I discuss, are becoming fundamental building blocks. This book is an invitation to reflect on these core ideas, which provide the foundation we need to build upon. Humans need these reflection moments on foundation patterns

所用框架简介

Introduction to the Frameworks Used

为了给我们的代码示例提供一个切实可行的“画布”（另见附录），我们将主要利用三个主流的智能体开发框架。LangChain 及其有状态扩展LangGraph 提供了一种灵活的方式来连接语言模型和其他组件，为构建复杂的操作序列和图提供了一个强大的平台。Crew AI 提供了一个专门用于协调多个 AI 智能体、角色和任务的结构化框架，尤其适合作为协作智能体系统的平台。Google智能体开发者工具包 (Google ADK) 提供了用于构建、评估和部署智能体的工具和组件，提供了另一个有价值的平台，并且通常与 Google 的 AI 基础架构集成。

To provide a tangible "canvas" for our code examples (see also Appendix), we will primarily utilize three prominent agent development frameworks. LangChain , along with its stateful extension LangGraph , provides a flexible way to chain together language models and other components, offering a robust canvas for building complex sequences and graphs of operations. Crew AI  provides a structured framework specifically designed for orchestrating multiple AI agents, roles, and tasks, acting as a canvas particularly well-suited for collaborative agent systems. The Google Agent Developer Kit (Google ADK)  offers tools and components for building, evaluating, and deploying agents, providing another valuable canvas, often integrated with Google's AI infrastructure.

这些框架代表了智能体开发画布的不同方面，各有优势。通过展示这些工具的示例，您可以更全面地了解如何应用这些模式，而无需考虑您为智能体系统选择的具体技术环境。这些示例旨在清晰地阐释模式的核心逻辑及其在框架画布上的实现，重点在于清晰性和实用性。

These frameworks represent different facets of the agent development canvas, each with its strengths. By showing examples across these tools, you will gain a broader understanding of how the patterns can be applied regardless of the specific technical environment you choose for your agentic systems. The examples are designed to clearly illustrate the pattern's core logic and its implementation on the framework's canvas, focusing on clarity and practicality.

读完本书，您不仅将理解 21 种基本智能体模式背后的基本概念，还将掌握有效应用这些模式的实践知识和代码示例，从而能够在您选择的开发平台上构建更智能、更强大、更自主的系统。让我们开始这段实践之旅吧！

By the end of this book, you will not only understand the fundamental concepts behind 21 essential agentic patterns but also possess the practical knowledge and code examples to apply them effectively, enabling you to build more intelligent, capable, and autonomous systems on your chosen development canvas. Let's begin this hands-on journey!

是什么让人工智能系统成为智能体？

What makes an AI system an Agent?

简而言之， 人工智能代理是  一个旨在感知环境并采取行动以实现特定目标的系统。它是标准大型语言模型 (LLM) 的演进，增强了规划、使用工具和与周围环境交互的能力。可以将智能代理人工智能想象成一个在工作中不断学习的智能助手。它遵循一个简单的五步循环来完成任务（见图 1）：

In simple terms, an AI agent  is a system designed to perceive its environment and take actions to achieve a specific goal. It's an evolution from a standard Large Language Model (LLM), enhanced with the abilities to plan, use tools, and interact with its surroundings. Think of an Agentic AI as a smart assistant that learns on the job . It follows a simple, five-step loop to get things done (see Fig.1):

1. 设定任务：  给它设定一个目标，例如“安排我的日程”。
2. Get the Mission:  You give it a goal, like "organize my schedule."
3. 扫描现场：  它收集所有必要的信息——阅读电子邮件、查看日历和访问联系人——以了解正在发生的事情。
4. Scan the Scene:  It gathers all the necessary information—reading emails, checking calendars, and accessing contacts—to understand what's happening.
5. 深思熟虑： 它通过考虑实现目标的最佳方法来制定行动计划。 
6. Think It Through:   It devises a plan of action by considering the optimal approach to achieve the goal.
7. 采取行动： 它会通过发送邀请、安排会议和更新日历来执行计划。 
8. Take Action:   It executes the plan by sending invitations, scheduling meetings, and updating your calendar.
9. 学习与改进： 系统会观察成功案例 并进行相应调整。例如，如果会议改期，系统会从中吸取经验教训，以提升未来的表现。   
10. Learn and Get Better:   It observes successful outcomes  and adapts accordingly.   For example, if a meeting is rescheduled, the system learns from this event to enhance its future performance.

图1： 智能体人工智能作为智能助手，通过不断的经验学习。 它通过一个简单的五步循环来完成任务。 

Fig.1: Agentic AI functions as an intelligent assistant, continuously learning through experience.   It operates via a straightforward five-step loop to accomplish tasks.

人工智能代理正以惊人的速度迅速普及。根据 近期 研究 ，大多数大型IT公司都在积极使用这些代理，其中五分之一的公司是在过去一年内才开始使用。金融市场也注意到了这一点。到2024年底，人工智能代理初创公司已筹集超过20亿美元资金，市场估值达到52亿美元。预计到2034年，该市场规模将爆炸式增长至近2000亿美元。简而言之，种种迹象表明，人工智能代理将在未来的经济中扮演举足轻重的角色。

Agents are becoming increasingly popular at a stunning pace. According to recent studies , a majority of large IT companies are actively using these agents, and a fifth of them just started within the past year. The financial markets are also taking notice. By the end of 2024, AI agent startups had raised more than $2 billion, and the market was valued at $5.2 billion. It's expected to explode to nearly $200 billion in value by 2034. In short, all signs point to AI agents playing a massive role in our future economy.

短短两年内，人工智能范式发生了翻天覆地的变化，从简单的自动化发展到复杂的自主系统（见图 2）。最初，工作流程依赖于基本的提示和触发器来处理使用逻辑学习模型（LLM）的数据。随着检索增强生成（RAG）技术的出现，这种方法得到了进一步发展，RAG 通过将模型建立在事实信息之上，提高了可靠性。随后，我们见证了能够使用各种工具的独立人工智能代理的出现。如今，我们正迈入智能体人工智能时代，在这个时代，由多个专业代理组成的团队协同工作，以实现复杂的目标，这标志着人工智能协作能力的显著提升。

In just two years, the AI paradigm has shifted dramatically, moving from simple automation to sophisticated, autonomous systems (see Fig. 2). Initially, workflows relied on basic prompts and triggers to process data with LLMs. This evolved with Retrieval-Augmented Generation (RAG), which enhanced reliability by grounding models on factual information. We then saw the development of individual AI Agents capable of using various tools.  Today, we are entering the era of Agentic AI, where a team of specialized agents works in concert to achieve complex goals, marking a significant leap in AI's collaborative power.

图 2：从 LLM过渡  到 RAG，再到 Agentic RAG，最后到 Agentic AI。

Fig 2.: Transitioning from LLMs  to RAG, then to Agentic RAG, and finally to Agentic AI.

本书旨在探讨专业代理如何协同工作以实现复杂目标的设计模式，每一章都会介绍一种协作和交互的范式。

The intent of this book is to discuss the design patterns of how  specialized agents can work in concert and collaborate to achieve  complex goals, and you will see one paradigm of collaboration and interaction in each chapter.

在此之前，让我们先来看一些涵盖不同智能体复杂程度的例子（见图 3）。

Before doing that, let's examine examples that span the range of agent complexity (see Fig. 3).

第 0 级：核心推理引擎

Level 0: The Core Reasoning Engine

虽然逻辑逻辑模型（LLM）本身并非智能体，但它可以作为基础智能体系统的推理核心。在“0级”配置下，LLM无需工具、记忆或环境交互即可运行，完全基于其预训练知识做出反应 。  它的优势在于能够利用其庞大的训练数据来解释既定概念。这种强大的内部推理能力的代价是完全缺乏对当前事件的感知。例如，如果2025年奥斯卡最佳影片的获奖信息超出其 预 训练知识范围，它就无法说出获奖影片。

While an LLM is not an agent in itself, it can serve as the reasoning core of a basic agentic system. In a 'Level 0' configuration, the LLM operates without tools, memory, or environment interaction, responding solely based on its pretrained knowledge .  Its strength lies in leveraging its extensive training data to explain established concepts. The trade-off for this powerful internal reasoning is a complete lack of current-event awareness. For instance, it would be unable to name the 2025 Oscar winner for "Best Picture" if that information is outside its pre- trained knowledge.

第一级：关联问题解决者

Level 1: The Connected Problem-Solver

在这个层面上，LLM 通过连接和利用外部工具，成为一个功能完善的智能体。它的解决问题能力不再局限于预训练的知识。相反，它可以执行一系列操作，从互联网（通过搜索）或数据库（通过检索增强生成，即 RAG）等来源收集和处理信息。 更多详细信息，请参阅第 14 章。

At this level, the LLM becomes a functional agent by connecting to and utilizing external tools. Its problem-solving is no longer limited to its pre-trained knowledge. Instead, it can execute a sequence of actions to gather and process information from sources like the internet (via search) or databases (via Retrieval Augmented Generation, or RAG). For detailed information, refer to Chapter 14.

例如，为了找到新的电视节目，智能体会识别出对最新信息的需求，使用搜索工具查找信息，然后综合分析结果。  至关重要的是，它还可以使用专门的工具来提高准确性，例如调用金融API来获取苹果公司（AAPL）的实时股价。这种与外部世界进行多步骤交互的能力是1级智能体的核心能力。

For instance, to find new TV shows, the agent recognizes the need for current information, uses a search tool to find it, and then synthesizes the results.  Crucially, it can also use specialized tools for higher accuracy, such as calling a financial API to get the live stock price for AAPL. This ability to interact with the outside world across multiple steps is the core capability of a Level 1 agent.

第二 级 ：战略问题解决者

Lev el  2: The Strategic Problem-Solver

在这个级别，代理的能力显著扩展，包括战略规划、主动协助和自我改进，而  快速工程和情境工程 是其核心赋能技能。

At this level, an agent's capabilities expand significantly, encompassing strategic planning, proactive assistance, and self-improvement, with  prompt engineering and context engineering a s core enabling skills.

首先，智能体不再局限于单一工具的使用，而是通过策略性问题解决来应对复杂的多部分问题。在执行一系列动作的过程中，它会主动进行 上下文工程：  即为每个步骤选择、打包和管理最相关的信息。例如，为了在两个地点之间找到一家咖啡店，它首先使用地图工具。然后，它会对地图输出进行处理，筛选出一个简短而集中的上下文——可能只是街道名称列表——并将其输入到本地搜索工具中，从而避免认知过载，确保第二步高效准确。为了使人工智能达到最高的准确率，必须为其提供简短、集中且有效的上下文。上下文 工程正是 通过策略性地选择、打包和管理来自所有可用来源的最关键信息来实现这一目标的学科。它有效地管理了模型有限的注意力，防止认知过载，并确保在任何给定任务上都能高效、高质量地完成任务 。 更多详细信息，请参阅附录 A。

First, the agent moves beyond single-tool use to tackle complex, multi-part problems through strategic problem-solving. As it executes a sequence of actions, it actively performs context engineering:  the strategic process of selecting, packaging, and managing the most relevant information for each step. For example, to find a coffee shop between two locations, it first uses a mapping tool. It then engineers this output, curating a short, focused context—perhaps just a list of street names—to feed into a local search tool, preventing cognitive overload and ensuring the second step is efficient and accurate. To achieve maximum accuracy from an AI, it must be given a short, focused, and powerful context. Context engineering i s the discipline that accomplishes this by strategically selecting, packaging, and managing the most critical information from all available sources. It effectively curates the model's limited attention to prevent overload and ensure high-quality, efficient performance on any given task . For detailed information, refer to the Appendix A.

这种  级别能够实现主动且持续的操作。与您的电子邮件关联的旅行助手就体现了这一点：它能够从冗长的航班确认邮件中提取上下文信息，并仅选取关键细节（航班号、日期、地点）进行打包，以便后续调用工具访问您的日历和天气 API。

This  level leads to proactive and continuous operation. A travel assistant linked to your email demonstrates this by engineering the context from a verbose flight confirmation email; it selects only the key details (flight numbers, dates, locations) to package for subsequent tool calls to your calendar and a weather API.

在软件工程等专业 领域，代理程序通过应用这种方法来管理整个工作流程。当接到缺陷报告时，它会读取报告并访问代码库，然后策略性地将这些庞大的信息源整合到一个高效且重点突出的上下文中，从而能够高效地编写、测试并提交正确的代码补丁。

In specialized fi elds like software engineering, the agent manages an entire workflow by applying this discipline. When assigned a bug report, it reads the report and accesses the codebase, then strategically engineers these large sources of information into a potent, focused context that allows it to efficiently write, test, and submit the correct code patch.

最后，智能体通过不断改进自身的上下文工程流程来实现自我提升。当它请求关于如何改进提示的反馈时，它实际上是在学习如何更好地整理初始输入。这使其能够 自动改进未来任务的信息打包方式  ，从而形成一个强大的自动化反馈循环，随着时间的推移不断提高其准确性和效率。 更多详细信息，请参阅第17章。

Finally, the agent achieves self-improvement by refining its own context engineering processes. When it asks for feedback on how a prompt could have been improved, it is learning how to better curate its initial inputs. This allows it to automatically improve how it packages information for  future tasks, creating a powerful, automated feedback loop that increases its accuracy and efficiency over time. For detailed information, refer to Chapter 17.

图 3： 各种实例展示了代理复杂性的谱系。

Fig. 3: Various instances demonstrating the spectrum of agent complexity.

第三级：协作式多智能体系统的兴起

Level 3: The Rise of Collaborative Multi-Agent Systems

在第三阶段，我们看到人工智能发展发生了重大范式转变，不再追求单一的、无所不能的超级智能体，而是转向构建复杂、协作的多智能体系统。本质上，这种方法认识到，解决复杂挑战的最佳方案往往不是由单个通才，而是由一群专家协同工作 。这种模型直接反映了人类组织的结构，其中不同的部门被赋予特定的角色，并协作应对多方面的目标。这种系统的整体力量源于这种分工以及通过协调努力所产生的协同效应。 更多详细信息，请参阅第七章。

At Level 3, we see a significant paradigm shift in AI development, moving away from the pursuit of a single, all-powerful super-agent and towards the rise of sophisticated, collaborative multi-agent systems. In essence, this approach recognizes that complex challenges are often best solved not by a single generalist, but by a team of specialists working in concert . This model directly mirrors the structure of a human organization, where different departments are assigned specific roles and collaborate to tackle multi-faceted objectives. The collective strength of such a system lies in this division of labor and the synergy created through coordinated effort. For detailed information, refer to Chapter 7.

为了更好地理解这个概念，不妨设想一下新产品上市的复杂流程。与其让一位专员试图包揽所有环节，不如设立一位“项目经理”作为中央协调人。这位经理将统筹整个流程，把任务分配给其他专业专员：例如，“市场调研”专员负责收集消费者数据，“产品设计”专员负责产品概念开发，“市场营销”专员负责制作宣传材料。他们成功的关键在于彼此之间顺畅的沟通和信息共享，确保所有人的努力都朝着共同的目标前进。

To bring this concept to life, consider the intricate workflow of launching a new product. Rather than one agent attempting to handle every aspect, a "Project Manager" agent could serve as the central coordinator. This manager would orchestrate the entire process by delegating tasks to other specialized agents: a "Market Research" agent to gather consumer data, a "Product Design" agent to develop concepts, and a "Marketing" agent to craft promotional materials. The key to their success would be the seamless communication and information sharing between them, ensuring all individual efforts align to achieve the collective goal.

尽管这种基于团队的自主自动化愿景已在发展之中，但我们必须正视当前面临的挑战。 此类多智能体系统的有效性目前受限于其所使用的逻辑逻辑模型（LLM）的推理能力。此外，它们之间真正相互学习并作为一个整体不断改进的能力仍处于起步阶段。克服这些技术瓶颈是至关重要的下一步，而这将释放这一层面的巨大潜力：实现从头到尾的整个业务流程的自动化。

While this vision of autonomous, team-based automation is already being developed, it's important to acknowledge the current hurdles. The effectiveness of  such multi-agent systems is presently constrained by the reasoning limitations of LLMs they are using. Furthermore, their ability to genuinely learn from one another and improve as a cohesive unit is still in its early stages. Overcoming these technological bottlenecks is the critical next step, and doing so will unlock the profound promise of this level: the ability to automate entire business workflows from start to finish.

智能体的未来：五大假设

The Future of Agents: Top 5 Hypotheses

人工智能代理的开发正以前所未有的速度在软件自动化、科学研究和客户服务等领域蓬勃发展。  尽管目前的系统令人印象深刻，但这仅仅是开始。下一波创新浪潮很可能聚焦于提升代理的可靠性、协作性和与我们生活的深度融合。以下是关于未来发展的五大主要假设（见图 4）。

AI agent development is progressing at an unprecedented pace across domains such as software automation, scientific research, and customer service among others.  While current systems are impressive, they are just the beginning. The next wave of innovation will likely focus on making agents more reliable, collaborative, and deeply integrated into our lives. Here are five leading hypotheses for what's next (see Fig. 4).

假设1：通才型主体的出现

Hypothesis 1: The Emergence of the Generalist Agent

第一个假设是，人工智能代理将从专精于特定领域的专家进化为真正的通才，能够以高可靠性管理复杂、模糊且长期的目标。例如，您可以给代理一个简单的指令：“为我公司下季度在里斯本举办的30人团建活动做计划。” 代理随后将管理整个项目数周，处理从预算审批、机票谈判到场地选择、根据员工反馈制定详细行程等所有事宜，并定期更新进度。要 实现这种程度的自主性，需要在人工智能推理、记忆和近乎完美的可靠性方面取得根本性的突破。另一种方法（并非与第一个假设互斥）是小型语言模型（ SLM ）的兴起 。这种“乐高式”的概念是指用小型、专业化的专家代理来构建系统，而不是扩展单一的整体模型。这种方法有望带来更便宜、调试更快、部署更便捷的系统。最终，大型通用模型的开发和小型专业模型的构建都是可行的前进方向，它们甚至可以相互补充。

The first hypothesis is that AI agents will evolve from narrow specialists into true generalists capable of managing complex, ambiguous, and long-term goals with high reliability. For instance, you could give an agent a simple prompt like, "Plan my company's offsite retreat for 30 people in Lisbon next quarter." The agent would then manage the entire project for weeks, handling everything from budget approvals and flight negotiations to venue selection and creating a detailed itinerary from employee feedback, all while providing regular updates. Achieving this level of autonomy will require fundamental breakthroughs in AI reasoning, memory, and near-perfect reliability. An alternative, yet not mutually exclusive, approach is the rise of Small Language Models ( SLMs ). This "Lego-like" concept involves composing systems from small, specialized expert agents rather than scaling up a single monolithic model. This method promises systems that are cheaper, faster to debug, and easier to deploy. Ultimately, the development of large generalist models and the composition of smaller specialized ones are both plausible paths forward, and they could even complement each other.

假设2：深度个性化和主动目标发现

Hypothesis 2: Deep Personalization and Proactive Goal Discovery

第二个假设认为，智能体将成为高度个性化且积极主动的合作伙伴。我们正在见证一种新型智能体的出现：积极主动的合作伙伴。 通过学习您独特的行为模式和目标，这些 系统正从单纯地执行指令转变为预测您的需求。 当人工智能系统不再仅仅响应聊天或指令时，它们就以智能体的身份运行。 它们代表用户发起并执行任务，并在过程中积极协作。  这超越了简单的任务执行，进入了主动发现目标的领域。 

The second hypothesis posits that agents will become deeply personalised and proactive partners. We are witnessing the emergence of a new class of agent: the proactive partner. By learning from your unique patterns and goals, thes e systems are beginning to shift from just following orders to anticipating your needs. AI systems operate as agents when they move beyond simply responding to chats or instructions.   They initiate and execute tasks on behalf of the user, actively collaborating in the process.   This moves beyond simple task execution into the realm of proactive goal discovery.

例如，如果您正在探索可持续能源，智能助手可能会识别出您的潜在目标，并通过推荐课程或总结研究成果来主动提供支持。虽然这些系统仍在发展中，但其发展轨迹清晰可见。它们将变得越来越主动，并在确信采取行动对您有益时，学会代表您主动行事。最终，智能助手将成为您不可或缺的盟友，帮助您发现并实现那些您尚未完全表达出来的抱负。

For instance, if you're exploring sustainable energy, the agent might identify your latent goal and proactively support it by suggesting courses or summarizing research. While these systems are still developing, their trajectory is clear. They will become increasingly proactive, learning to take initiative on your behalf when highly confident that the action will be helpful. Ultimately, the agent becomes an indispensable ally, helping you discover and achieve ambitions you have yet to fully articulate.

图 4： 关于代理人未来的五种 假设

Fig. 4: Five  hypot heses about the future of agents

假设3： 具身认知与物理世界互动

Hypothesis 3: Embodiment and Physical World Interaction

这一假设预见了智能体将突破纯粹的数字限制，在现实世界中运作。通过将智能体人工智能与机器人技术相结合，我们将见证“具身智能体”的兴起。届时，您或许不再只是预约一位勤杂工，而是可以请您的智能体修理漏水的水龙头。智能体将利用其视觉传感器感知问题，访问管道知识库制定维修方案，然后精准地控制其机械臂完成维修。这将是一个里程碑式的进步，它弥合了数字智能与物理行动之间的鸿沟，并将彻底改变从制造业、物流业到老年护理和家庭维护等各个领域。

This hypothesis foresees agents breaking free from their purely digital confines to operate in the physical world. By integrating agentic AI with robotics, we will see the rise of " embodied agents ." Instead of just booking a handyman, you might ask your home agent to fix a leaky tap. The agent would use its vision sensors to perceive the problem, access a library of plumbing knowledge to formulate a plan, and then control its robotic manipulators with precision to perform the repair. This would represent a monumental step, bridging the gap between digital intelligence and physical action, and transforming everything from manufacturing and logistics to elder care and home maintenance.

假设4：主体驱动经济  

Hypothesis 4: The Agent-Driven Economy  

第四个假设是，高度自主的智能体将成为  经济活动的积极参与者，创造新的市场和商业模式。 我们可以设想，智能体作为独立的经济实体，以最大化特定目标（例如利润）为己任。企业家可以启动一个智能体来运营整个电子商务业务。该智能体将通过分析社交媒体来识别热门产品，生成营销文案和视觉素材，通过与其他自动化系统交互来管理供应链物流，并根据实时需求动态调整价格。这种转变将创造一个全新的、超高效的“智能体经济”，其运行速度和规模是人类直接管理的极限。

The fourth hypothesis is that highly autonomous agents will become active  participants in the economy, creating new markets and business models. We could see agents acting as independent economic entities, tasked with maximising a specific outcome, such as profit. An entrepreneur could launch an agent to run an entire e-commerce business. The agent would identify trending products by analysing social media, generate marketing copy and visuals, manage supply chain logistics by interacting with other automated systems, and dynamically adjust pricing based on real-time demand. This shift would create a new, hyper-efficient "agent economy" operating at a speed and scale impossible for humans to manage directly.

假设5：  目标驱动的变形多智能体系统

Hypothesis 5:  The Goal-Driven, Metamorphic Multi-Agent System

这一假设提出，智能系统将不再依赖显式编程，而是根据预设目标运行。用户只需陈述期望的结果，系统便能自主地找到实现目标的方法。这标志着智能系统向  能够真正实现个体和群体自我完善的、可变形的多智能体系统发生了根本性的转变。

This hypothesis posits the emergence of intelligent systems that operate not from explicit programming, but from a declared goal. The user simply states the desired outcome, and the system autonomously figures out how to achieve it. This marks a fundamental shift towards metamorphic multi-agent systems  capable of true self-improvement at both the individual and collective levels.

该系统将是一个动态实体，而非单一主体。它能够分析自身性能，并根据需要调整其多主体团队的拓扑结构，创建、复制或移除主体，从而组建最高效的团队来完成当前任务。这种演化发生在多个层面：

This system would be a dynamic entity, not a single agent. It would have the ability to analyze its own performance and modify the topology of its multi-agent workforce, creating, duplicating, or removing agents as needed to form the most effective team for the task at hand. This evolution happens at multiple levels:

• 架构修改：从最深层次上看，各个代理可以重写自己的源代码，并重新构建其内部结构以提高效率，正如最初的假设一样。
• Architectural Modification: At the deepest level, individual agents can rewrite their own source code and re-architect their internal structures for higher efficiency, as in the original hypothesis.
• 指令修正：在更高层面上，系统持续进行自动提示工程和上下文工程。它优化发送给每个代理的指令和信息，确保它们在无需人工干预的情况下获得最佳指导。
• Instructional Modification: At a higher level, the system continuously performs automatic prompt engineering and context engineering. It refines the instructions and information given to each agent, ensuring they are operating with optimal guidance without any human intervention.

例如，一位创业者只需声明其意图：“创办一家成功的电子商务企业，销售手工咖啡。” 系统无需进一步编程，即可立即启动。它最初可能会生成一个“市场调研”代理和一个“品牌推广”代理。根据初步调研结果，系统可能会决定移除品牌推广代理，并生成三个新的专业代理：“Logo设计”代理、“网店平台”代理和“供应链”代理。系统会不断调整这些代理的内部指令，以提升其性能。如果网店代理成为瓶颈，系统可能会将其复制成三个并行代理，分别负责网站的不同部分，从而有效地动态重构自身架构，以最佳方式实现既定 目标。

For instance, an entrepreneur would simply declare the intent: "Launch a successful e-commerce business selling artisanal coffee." The system, without further programming, would spring into action. It might initially spawn a "Market Research" agent and a "Branding" agent. Based on the initial findings, it could decide to remove the branding agent and spawn three new specialized agents: a "Logo Design" agent, a "Webstore Platform" agent, and a "Supply Chain" agent. It would constantly tune their internal prompts for better performance. If the webstore agent becomes a bottleneck, the system might duplicate it into three parallel agents to work on different parts of the site, effectively re-architecting its own structure on the fly to best achieve the declared goal.

结论

Conclusion

本质上，人工智能代理代表着对传统模型的重大飞跃，它作为一个自主系统，能够感知、规划并采取行动以实现特定目标。这项技术的发展正从单一的、使用工具的代理，逐步迈向能够处理多方面目标的复杂协作式多代理系统。未来的设想预测，通用型、个性化甚至实体化的代理将会出现，并成为经济活动的积极参与者。这一持续发展标志着一次重大的范式转变，即朝着自我改进、目标驱动的系统迈进，这些系统有望实现整个工作流程的自动化，并从根本上重新定义我们与技术的关系。

In essence, an AI agent represents a significant leap from traditional models, functioning as an autonomous system that perceives, plans, and acts to achieve specific goals. The evolution of this technology is advancing from single, tool-using agents to complex, collaborative multi-agent systems that tackle multifaceted objectives. Future hypotheses predict the emergence of generalist, personalized, and even physically embodied agents that will become active participants in the economy. This ongoing development signals a major paradigm shift towards self-improving, goal-driven systems poised to automate entire workflows and fundamentally redefine our relationship with technology.

参考

References

1. Cloudera公司（2025年4月）的数据显示，96%的企业正在增加对人工智能代理的使用。https ://www.cloudera.com/about/news-and-blogs/press-releases/2025-04-16-96-percent-of-enterprises-are-expanding-use-of-ai-agents-according-to-latest-data-from-cloudera.html  
2. Cloudera, Inc. (April 2025), 96% of enterprises are increasing their use of AI agents. https://www.cloudera.com/about/news-and-blogs/press-releases/2025-04-16-96-percent-of-enterprises-are-expanding-use-of-ai-agents-according-to-latest-data-from-cloudera.html  
3. 自主生成式人工智能代理： https://www.deloitte.com/us/en/insights/industry/technology/technology-media-and-telecom-predictions/2025/autonomous-generative-ai-agents-still-under-development.html  
4. Autonomous generative AI agents: https://www.deloitte.com/us/en/insights/industry/technology/technology-media-and-telecom-predictions/2025/autonomous-generative-ai-agents-still-under-development.html  
5. Market.us. 全球智能体人工智能市场规模、趋势及预测（2025-2034 年）。https ://market.us/report/agentic-ai-market/     
6. Market.us.   Global Agentic AI Market Size, Trends and Forecast 2025–2034 .   https://market.us/report/agentic-ai-market/  

第一章：提示 链

Chapter 1: Prompt Chaining

提示链模式概述

Prompt Chaining Pattern Overview

提示链（有时也称为管道模式）是一种强大的范式，可用于处理利用大型语言模型 (LLM) 时遇到的复杂任务。 提示链并不期望 LLM 一次性解决复杂问题，而是提倡分而治之的策略。其核心思想是将最初看似棘手的问题分解成一系列更小、更易于管理的子问题。每个子问题都通过专门设计的提示进行单独处理，并且一个提示的输出会策略性地作为输入传递给链中的下一个提示。     

Prompt chaining, sometimes referred to as Pipeline pattern, represents a powerful paradigm for handling intricate tasks when leveraging large language models (LLMs).   Rather than expecting an LLM to solve a complex problem in a single, monolithic step, prompt chaining advocates for a divide-and-conquer strategy.   The core idea is to break down the original, daunting problem into a sequence of smaller, more manageable s ub-prob lems.   Each sub-problem is addressed individually through a specifically designed prompt, and the output generated from one prompt is strategically fed as input into the subsequent prompt in the chain.

这种顺序处理技术从本质上为与逻辑逻辑模型（LLM）的交互引入了模块化和清晰度。通过分解复杂任务，可以更轻松地理解和调试每个步骤，从而使整个过程更加稳健和易于解释。 链中的每个步骤都可以精心设计和优化，以专注于更大问题的特定方面，从而获得更准确、更有针对性的输出。 

This sequential processing technique inherently introduces modularity and clarity into the interaction with LLMs. By decomposing a complex task, it becomes easier to understand and debug each individual step, making the overall process more robust and interpretable.   Each step in the chain can be meticulously crafted and optimized to focus on a specific aspect of the larger problem, leading to more accurate and focused outputs.

前一步骤的输出作为下一步骤的输入至关重要。 这种信息传递建立了一个依赖链（这也是“依赖链”名称的由来），其中先前操作的上下文和结果指导着后续的处理。这使得LLM能够在前期工作的基础上不断完善理解，并逐步接近理想的解决方案。   

The output of one step acting as the input for the next is crucial.   This passing of information establishes a dependency chain, hence the name, where the context and results of previous operations guide the subsequent processing.   This allows the LLM to build on its previous work, refine its understanding, and progressively move closer to the desired solution.

此外，提示链式推理不仅能分解问题，还能整合外部知识和工具。 在每个步骤中，LLM 都可以被指示与外部系统、API 或数据库交互，从而拓展其知识和能力，使其超越内部训练数据。这种能力极大地扩展了 LLM 的潜力，使其不仅能作为独立模型运行，还能作为更广泛、更智能系统的组成部分发挥作用。   

Furthermore, prompt chaining is not just about breaking down problems; it also enables the integration of external knowledge and tools.   At each step, the LLM can be instructed to interact with external systems, APIs, or databases, enriching its knowledge and abilities beyond its internal training data.   This capability dramatically expands the potential of LLMs, allowing them to function not just as isolated models but as integral components of broader, more intelligent systems.

提示链的意义远不止于简单的解决问题。 它是一种构建复杂人工智能体的基础技术。这些智能体可以利用提示链在动态环境中自主地进行规划、推理和行动。通过策略性地构建提示序列，智能体可以执行需要多步骤推理、规划和决策的任务。这种智能体的工作流程能够更贴近人类的思维过程，从而实现与复杂领域和系统更自然、更高效的交互。       

The significance of prompt chaining extends beyond simple problem-solving.   It serves as a foundational technique for building sophisticated AI agents.   These agents can utilize prompt chains to autonomously plan, reason, and act in dynamic environments.   By strategically structuring the sequence of prompts, an agent can engage in tasks requiring multi-step reasoning, planning, and decision-making.   Such agent workflows can mimic human thought processes more closely, allowing for more natural and effective interactions with complex domains and systems.

单一提示 的局限性： 对于多方面任务，使用单一且复杂的提示进行逻辑学习模型（LLM）可能效率低下，导致模型难以处理约束和指令，进而可能出现指令忽略（即忽略提示的某些部分）、上下文漂移（即模型丢失初始上下文）、错误传播（即早期错误被放大）、需要较长上下文窗口的提示（即模型获取的信息不足以做出响应）以及幻觉（即认知负荷增加导致错误信息出现的概率）。例如，要求分析市场调研报告、总结调查结果、识别数据点中的趋势并撰写电子邮件的查询，可能会失败，因为模型可能能够很好地总结结果，但却无法正确提取数据或撰写电子邮件。   

Limitations of single prompts :   For multifaceted tasks, using a single, complex prompt for an LLM can be inefficient, causing the model to struggle with constraints and instructions, potentially leading to instruction neglect where parts of the prompt are overlooked, contextual drift where the model loses track of the initial context, error propagation where early errors amplify, prompts which require a longer context window where the model gets insufficient information to respond back and hallucination where the cognitive load increases the chance of incorrect information.   For example, a query asking to analyze a market research report, summarize findings, identify trends with data points, and draft an email risks failure as the model might summarize well but fail to extract data or draft an email properly.

通过顺序分解增强可靠性： 提示链式方法通过将复杂任务分解为专注的顺序工作流程来应对这些挑战，从而显著提高可靠性和可控性 。 以 上述示例为例，流水线或链式方法可以描述如下 ：

Enhanced Reliability Through Sequential Decomposition: Prompt chaining addresses these challenges by breaking the complex task into a focused, sequential workflow, which significantly improves reliability and control . G iven the example above, a pipeline or chained approach can be described as follows :

1. 初始提示（总结）：“总结以下市场调研报告的主要发现：[文本]。”该模型的唯一重点是总结，从而提高初始步骤的准确性。
2. Initial Prompt (Summarization): "Summarize the key findings of the following market research report: [text]." The model's sole focus is summarization, increasing the accuracy of this initial step.
3. 第二个提示（趋势识别）：“利用摘要，识别出三大新兴趋势，并提取支持每个趋势的具体数据点：[步骤 1 的输出]。” 此提示现在更具约束性，并且直接建立在已验证的输出之上。
4. Second Prompt (Trend Identification): "Using the summary, identify the top three emerging trends and extract the specific data points that support each trend: [output from step 1]." This prompt is now more constrained and builds directly upon a validated output.
5. 第三项提示（电子邮件撰写）：“请为市场营销团队撰写一封简洁的电子邮件，概述以下趋势及其支持数据：[步骤 2 的输出]。”
6. Third Prompt (Email Composition): "Draft a concise email to the marketing team that outlines the following trends and their supporting data: [output from step 2]."

这种分解方式能够对流程进行更精细的控制。每个步骤都更加简单明了，从而降低了模型的认知负荷，并最终产生更准确可靠的输出。这种模块化类似于计算流水线，其中每个函数执行特定的操作，然后将结果传递给下一个函数。 为了确保对每个特定任务都能做出准确的响应，可以在每个阶段为模型分配不同的角色。 例如，在给定的场景中，初始提示可以指定为“市场分析师”，后续提示可以指定为“交易分析师”，第三个提示可以指定为“专家文档撰写员”，依此类推。 

This decomposition allows for more granular control over the process. Each step is simpler and less ambiguous, which reduces the cognitive load on the model and leads to a more accurate and reliable final output. This modularity is analogous to a computational pipeline where each function performs a specific operation before passing its result to the next. To ensure an accurate response for each specific task, the model can be assigned a distinct role at every stage.   For example, in the given scenario, the initial prompt could be designated as "Market Analyst," the subsequent prompt as "Trade Analyst," and the third prompt as "Expert Documentation Writer," and so forth.

结构化输出的作用： 提示链的可靠性高度依赖于各步骤之间传递的数据的完整性。如果一个提示的输出含糊不清或格式错误，后续提示可能会因为输入错误而失败。为了避免这种情况，指定 结构化输出格式（例如 JSON 或 XML）至关重要。

The Role of Structured Output: The reliability of a prompt chain is highly dependent on the integrity of the data passed between steps. If the output of one prompt is ambiguous or poorly formatted, the subsequent prompt may fail due to faulty input. To mitigate this, specifying a structured output format, such as JSON or XML, is crucial.

例如，趋势识别步骤 的输出 可以格式化为 JSON 对象：

For example, the output from the trend identification step could be formatted as a JSON object:

{  "trends": [    {      "trend_name": "AI-Powered Personalization",      "supporting_data": "73% of consumers prefer to do business with brands that use personal information to make their shopping experiences more relevant."    },    {      "trend_name": "Sustainable and Ethical Brands",      "supporting_data": "Sales of products with ESG-related claims grew 28% over the last five years, compared to 20% for products without."    }  ] }

这种结构化格式确保数据可被机器读取，并能被精确解析，无歧义地插入到下一个提示中。这种做法最大限度地减少了自然语言解释过程中可能出现的错误，是构建稳健的多步骤LLM系统的关键组成部分。

This structured format ensures that the data is machine-readable and can be precisely parsed and inserted into the next prompt without ambiguity. This practice minimizes errors that can arise from interpreting natural language and is a key component in building robust, multi-step LLM-based systems.

实际应用及案例

Practical Applications & Use Cases

提示链是一种用途广泛的模式，适用于构建智能体系统的各种场景。它的核心优势在于将复杂问题分解为一系列顺序的、可管理的步骤。以下是一些实际应用和用例：

Prompt chaining is a versatile pattern applicable in a wide range of scenarios when building agentic systems. Its core utility lies in breaking down complex problems into sequential, manageable steps. Here are several practical applications and use cases:

1. 信息处理工作流程：  许多任务涉及通过多次转换来处理原始信息。例如，摘要文档、提取关键实体，然后使用这些实体查询数据库或生成报告。一个提示链可能如下所示：

1. Information Processing Workflows:  Many tasks involve processing raw information through multiple transformations. For instance, summarizing a document, extracting key entities, and then using those entities to query a database or generate a report. A prompt chain could look like:

• 提示 1：从给定的 URL 或文档中提取文本内容。
• Prompt 1: Extract text content from a given URL or document.
• 提示 2：总结清理后的文本。
• Prompt 2: Summarize the cleaned text.
• 提示 3：从摘要或原文中提取特定实体（例如，名称、日期、地点）。
• Prompt 3: Extract specific entities (e.g., names, dates, locations) from the summary or original text.
• 提示 4：使用这些实体搜索内部知识库。
• Prompt 4: Use the entities to search an internal knowledge base.
• 提示 5：生成包含摘要、实体和搜索结果的最终报告。
• Prompt 5: Generate a final report incorporating the summary, entities, and search results.

该方法应用于自动化内容分析、人工智能驱动的研究助手开发以及复杂报告生成等领域。

This methodology is applied in domains such as automated content analysis, the development of AI-driven research assistants, and complex report generation.

2. 复杂查询回答：  回答需要多步骤推理或信息检索的复杂问题是其主要应用场景。例如，“1929年股市崩盘的主要原因是什么？政府政策是如何应对的？”

2. Complex Query Answering:  Answering complex questions that require multiple steps of reasoning or information retrieval is a prime use case. For example, "What were the main causes of the stock market crash in 1929, and how did government policy respond?"

• 提示 1：确定用户查询中的核心子问题（事故原因、政府应对措施）。
• Prompt 1: Identify the core sub-questions in the user's query (causes of crash, government response).
• 提示 2：研究或检索有关 1929 年空难原因的具体信息。
• Prompt 2: Research or retrieve information specifically about the causes of the 1929 crash.
• 提示 3：研究或检索有关 政府对 1929 年股市崩盘的政策应对措施的具体信息。
• Prompt 3: Research or retrieve information specifically about the government's policy response to the 1929 stock market crash.
• 提示 4：将步骤 2 和 3 中的信息综合起来，形成对原始问题的连贯答案。
• Prompt 4: Synthesize the information from steps 2 and 3 into a coherent answer to the original query.

这种顺序处理方法是开发能够进行多步骤推理和信息综合的人工智能系统的关键所在。当一个查询无法仅凭单个数据点回答，而需要一系列逻辑步骤或整合来自不同来源的信息时，就需要这类系统。

This sequential processing methodology is integral to developing AI systems capable of multi-step inference and information synthesis. Such systems are required when a query cannot be answered from a single data point but instead necessitates a series of logical steps or the integration of information from diverse sources.

例如，一个旨在生成特定主题综合报告的自动化研究代理会执行混合计算工作流程。首先，系统会检索大量相关文章。随后，可以从每篇文章中提取关键信息，这项任务可以针对每个来源并行执行。这一阶段非常适合并行处理，通过同时运行独立的子任务来最大限度地提高效率。

For example, an automated research agent designed to generate a comprehensive report on a specific topic executes a hybrid computational workflow. Initially, the system retrieves numerous relevant articles. The subsequent task of extracting key information from each article can be performed concurrently for each source. This stage is well-suited for parallel processing, where independent sub-tasks are run simultaneously to maximize efficiency.

然而，一旦各个数据提取步骤完成，整个流程就呈现出固有的顺序性。系统必须首先整理提取的数据，然后将其综合成一份连贯的草稿，最后审核并完善这份草稿，最终生成一份报告。每个后续阶段在逻辑上都依赖于前一个阶段的成功完成。这就是提示链的应用之处：整理后的数据作为综合提示的输入，而生成的综合文本则作为最终审核提示的输入。因此，复杂的操作通常会结合并行处理（用于独立数据收集）和提示链（用于综合和完善这两个依赖步骤）。

However, once the individual extractions are complete, the process becomes inherently sequential. The system must first collate the extracted data, then synthesize it into a coherent draft, and finally review and refine this draft to produce a final report. Each of these later stages is logically dependent on the successful completion of the preceding one. This is where prompt chaining is applied: the collated data serves as the input for the synthesis prompt, and the resulting synthesized text becomes the input for the final review prompt. Therefore, complex operations frequently combine parallel processing for independent data gathering with prompt chaining for the dependent steps of synthesis and refinement.

3. 数据提取和转换： 将非结构化文本转换为结构化格式通常是通过 迭代  过程实现的，需要进行顺序修改以提高输出的准确性和完整性。

3. Data Extraction and Transformation: The conversion of unstructured text into a structured format is typically achieved through an iterative  process, requiring sequential modifications to improve the accuracy and completeness of the output.

• 提示 1：尝试从发票文档中提取特定字段（例如，姓名、地址、金额）。
• Prompt 1: Attempt to extract specific fields (e.g., name, address, amount) from an invoice document.
• 处理：检查是否已提取所有必需字段，以及它们是否符合格式要求。
• Processing: Check if all required fields were extracted and if they meet format requirements.
• 提示 2（条件）：如果字段缺失或格式错误，则创建一个新提示，要求模型专门查找缺失/格式错误的信息，并可能提供失败尝试的上下文。
• Prompt 2 (Conditional): If fields are missing or malformed, craft a new prompt asking the model to specifically find the missing/malformed information, perhaps providing context from the failed attempt.
• 后续步骤：再次验证结果。如有必要，重复上述步骤。
• Processing: Validate the results again. Repeat if necessary.
• 输出：提供提取的、经过验证的结构化数据。
• Output: Provide the extracted, validated structured data.

这种顺序处理方法尤其适用于从非结构化数据源（例如表单、发票或电子邮件）中提取和分析数据。例如，解决复杂的光学字符识别 (OCR) 问题（例如处理 PDF 表单）通过分解的多步骤方法可以更有效地完成。

This sequential processing methodology is particularly applicable to data extraction and analysis from unstructured sources like forms, invoices, or emails. For example, solving complex Optical Character Recognition (OCR) problems, such as processing a PDF form, is more effectively handled through a decomposed, multi-step approach.

首先，系统采用大型语言模型（LLM）从文档图像中提取文本。随后，模型处理原始输出以规范化数据，例如将“一千零五十”等数值文本转换为其等效值 1050。LLM 面临的一大挑战是执行精确的数学运算。因此，在后续步骤中，系统可以将所需的算术运算委托给外部计算器工具。LLM 识别必要的计算，将规范化后的数字输入到工具中，然后应用计算结果。这种文本提取、数据规范化和使用外部工具的链式流程最终能够获得精确的结果，而这通常难以通过单个 LLM 查询可靠地获得。

Initially, a large language model is employed to perform the primary text extraction from the document image. Following this, the model processes the raw output to normalize the data, a step where it might convert numeric text, such as "one thousand and fifty," into its numerical equivalent, 1050. A significant challenge for LLMs is performing precise mathematical calculations. Therefore, in a subsequent step, the system can delegate any required arithmetic operations to an external calculator tool. The LLM identifies the necessary calculation, feeds the normalized numbers to the tool, and then incorporates the precise result. This chained sequence of text extraction, data normalization, and external tool use achieves a final, accurate result that is often difficult to obtain reliably from a single LLM query.

4. 内容生成工作流程：  复杂内容的创作是一个程序化的任务，通常分解为不同的阶段，包括初步构思、结构概述、草拟和后续修订。

4. Content Generation Workflows:  The composition of complex content is a procedural task that is typically decomposed into distinct phases, including initial ideation, structural outlining, drafting, and subsequent revision

• 提示 1：根据用户的普遍兴趣生成 5 个主题想法。
• Prompt 1: Generate 5 topic ideas based on a user's general interest.
• 处理方式：允许用户选择一个想法或自动选择最佳想法。
• Processing: Allow the user to select one idea or automatically choose the best one.
• 提示 2：根据所选主题，生成详细提纲。
• Prompt 2: Based on the selected topic, generate a detailed outline.
• 提示 3：根据提纲中的第一点，写出一个草稿章节。
• Prompt 3: Write a draft section based on the first point in the outline.
• 提示 4：根据提纲中的第二点，撰写一个草稿章节，并提供前一章节作为背景。对所有提纲要点重复此操作。
• Prompt 4: Write a draft section based on the second point in the outline, providing the previous section for context. Continue this for all outline points.
• 提示 5：审阅并完善完整草稿，使其连贯、语气和语法正确。
• Prompt 5: Review and refine the complete draft for coherence, tone, and grammar.

该方法适用于一系列自然语言生成任务，包括自动生成创意叙事、技术文档和其他形式的结构化文本内容。

This methodology is employed for a range of natural language generation tasks, including the automated composition of creative narratives, technical documentation, and other forms of structured textual content.

5. 具有状态的对话代理：  尽管全面的状态管理架构采用的方法比顺序链接更为复杂，但提示链为保持对话的连续性提供了一种基础机制。该技术通过将每个对话回合构建为一个新的提示来维护上下文，该提示系统地整合了对话序列中先前交互的信息或提取的实体。

5. Conversational Agents with State:  Although comprehensive state management architectures employ methods more complex than sequential linking, prompt chaining provides a foundational mechanism for preserving conversational continuity. This technique maintains context by constructing each conversational turn as a new prompt that systematically incorporates information or extracted entities from preceding interactions in the dialogue sequence.

• 提示 1：处理用户话语 1，识别意图和关键实体。
• Prompt 1: Process User Utterance 1, identify intent and key entities.
• 处理：根据意图和实体更新对话状态。
• Processing: Update conversation state with intent and entities.
• 提示 2：根据当前状态，生成响应和/或确定下一个所需信息。
• Prompt 2: Based on current state, generate a response and/or identify the next required piece of information.
• 重复后续回合，每个新用户的发言都会启动一个利用不断积累的对话历史（状态）的链。
• Repeat for subsequent turns, with each new user utterance initiating a chain that leverages the accumulating conversation history (state).

这一原则对于对话代理的开发至关重要，它使代理能够在长时间的多轮对话中保持上下文的连贯性和一致性。通过保留对话历史，系统能够理解并恰当地响应依赖于先前交流信息的用户输入。

This principle is fundamental to the development of conversational agents, enabling them to maintain context and coherence across extended, multi-turn dialogues. By preserving the conversational history, the system can understand and appropriately respond to user inputs that depend on previously exchanged information.

6. 代码生成与优化：  功能代码的生成通常是一个多阶段过程，需要将问题分解为一系列离散的逻辑操作，并逐步执行这些操作。

6. Code Generation and Refinement:  The generation of functional code is typically a multi-stage process, requiring a problem to be decomposed into a sequence of discrete logical operations that are executed progressively

• 提示 1：理解用户对代码功能的请求。生成伪代码或概要。
• Prompt 1: Understand the user's request for a code function. Generate pseudocode or an outline.
• 提示 2：根据大纲编写初始代码草稿。
• Prompt 2: Write the initial code draft based on the outline.
• 提示 3：识别代码中潜在的错误或需要改进的地方（或许可以使用静态分析工具或其他 LLM 调用）。
• Prompt 3: Identify potential errors or areas for improvement in the code (perhaps using a static analysis tool or another LLM call).
• 提示 4：根据已发现的问题重写或改进代码。
• Prompt 4: Rewrite or refine the code based on the identified issues.
• 提示 5：添加文档或测试用例。
• Prompt 5: Add documentation or test cases.

在人工智能辅助软件开发等应用中，提示链的实用性源于其将复杂的编码任务分解为一系列易于管理的子问题的能力。这种模块化结构降低了大型语言模型在每个步骤中的操作复杂度。至关重要的是，这种方法还允许在模型调用之间插入确定性逻辑，从而在工作流中实现中间数据处理、输出验证和条件分支。通过这种方法，原本可能导致不可靠或不完整结果的单个多方面请求被转换为由底层执行框架管理的结构化操作序列。

In applications such as AI-assisted software development, the utility of prompt chaining stems from its capacity to decompose complex coding tasks into a series of manageable sub-problems. This modular structure reduces the operational complexity for the large language model at each step. Critically, this approach also allows for the insertion of deterministic logic between model calls, enabling intermediate data processing, output validation, and conditional branching within the workflow. By this method, a single, multifaceted request that could otherwise lead to unreliable or incomplete results is converted into a structured sequence of operations managed by an underlying execution framework.

7. 多模态和多步骤推理： 分析包含多种模态的数据集需要将问题分解成更小的、基于提示的任务。 例如，解读包含嵌入文本的图片、突出显示特定文本片段的标签以及解释每个标签的表格数据的图像，就需要采用这种方法。 

7. Multimodal and multi-step reasoning: Analyzing datasets with diverse modalities necessitates breaking down the problem into smaller, prompt-based tasks.   For example, interpreting an image that contains a picture with embedded text, labels highlighting specific text segments, and tabular data explaining each label, requires such an approach.

• 提示 1：从用户的图像请求中提取并理解文本。
• Prompt 1: Extract and comprehend the text from the user's image request.
• 提示 2：将提取的图像文本与其对应的标签关联起来。
• Prompt 2: Link the extracted image text with its corresponding labels.
• 提示 3：使用表格解释收集到的信息，以确定所需的输出 。
• Prompt 3: Interpret the gathered information using a table to determine the required output .

动手实践代码示例

Hands-On Code Example

实现提示链的方法多种多样，从脚本中直接按顺序调用函数，到利用专门设计的框架来管理控制流、状态和组件集成，不一而足。诸如 LangChain、LangGraph、Crew AI 和 Google Agent Development Kit (ADK) 等框架为构建和执行这些多步骤流程提供了结构化的环境，这对于复杂的架构尤为有利。

Implementing prompt chaining ranges from direct, sequential function calls within a script to the utilization of specialized frameworks designed to manage control flow, state, and component integration. Frameworks such as LangChain, LangGraph, Crew AI, and the Google Agent Development Kit (ADK) offer structured environments for constructing and executing these multi-step processes, which is particularly advantageous for complex architectures.

为了演示，LangChain 和 LangGraph 是合适的选择，因为它们的核心 API 专门设计用于构建操作链和操作图。LangChain 为线性序列提供基础抽象，而 LangGraph 则扩展了这些功能，以支持有状态和循环计算，这对于实现更复杂的智能体行为至关重要。本示例将重点介绍一个基本的线性序列。

For the purpose of demonstration, LangChain and LangGraph are suitable choices as their core APIs are explicitly designed for composing chains and graphs of operations. LangChain provides foundational abstractions for linear sequences, while LangGraph extends these capabilities to support stateful and cyclical computations, which are necessary for implementing more sophisticated agentic behaviors. This example will focus on a fundamental linear sequence.

以下代码实现了一个两步提示链，作为数据处理管道。初始阶段旨在解析非结构化文本并提取特定信息。后续阶段接收提取的输出并将其转换为结构化数据格式。

The following code implements a two-step prompt chain that functions as a data processing pipeline. The initial stage is designed to parse unstructured text and extract specific information. The subsequent stage then receives this extracted output and transforms it into a structured data format.

要复现此过程，必须先安装所需的库。可以使用以下命令完成此操作：

To replicate this procedure, the required libraries must first be installed. This can be accomplished using the following command:

pip install langchain langchain-community langchain-openai langgraph

请注意，langchain-openai 可以替换为其他模型提供商的相应软件包。随后，必须使用所选语言模型提供商（例如 OpenAI、Google Gemini 或 Anthropic）所需的 API 凭据配置执行环境。

Note that langchain-openai can be substituted with the appropriate package for a different model provider. Subsequently, the execution environment must be configured with the necessary API credentials for the selected language model provider, such as OpenAI, Google Gemini, or Anthropic.

import os from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser # For better security, load environment variables from a .env file # from dotenv import load_dotenv # load_dotenv() # Make sure your OPENAI_API_KEY is set in the .env file # Initialize the Language Model (using ChatOpenAI is recommended) llm = ChatOpenAI(temperature=0) # --- Prompt 1: Extract Information --- prompt_extract = ChatPromptTemplate.from_template(    "Extract the technical specifications from the following text:\n\n{text_input}" ) # --- Prompt 2: Transform to JSON --- prompt_transform = ChatPromptTemplate.from_template(    "Transform the following specifications into a JSON object with 'cpu', 'memory', and 'storage' as keys:\n\n{specifications}" ) # --- Build the Chain using LCEL --- # The StrOutputParser() converts the LLM's message output to a simple string. extraction_chain = prompt_extract | llm | StrOutputParser() # The full chain passes the output of the extraction chain into the 'specifications' # variable for the transformation prompt. full_chain = (    {"specifications": extraction_chain}    | prompt_transform    | llm    | StrOutputParser() ) # --- Run the Chain --- input_text = "The new laptop model features a 3.5 GHz octa-core processor, 16GB of RAM, and a 1TB NVMe SSD." # Execute the chain with the input text dictionary. final_result = full_chain.invoke({"text_input": input_text}) print("\n--- Final JSON Output ---") print(final_result)

这段 Python 代码演示了如何使用 LangChain 库处理文本。它使用了两个独立的提示：一个用于从输入字符串中提取技术规格，另一个用于将这些规格格式化为 JSON 对象。代码采用 ChatOpenAI 模型进行语言模型交互，并使用 StrOutputParser 确保输出为可用的字符串格式。LangChain 表达式语言 (LCEL) 用于将这些提示和语言模型优雅地链接在一起。第一个链 `extraction_chain` 用于提取规格。`full_chain` 则将提取的输出作为转换提示的输入。代码提供了一个描述笔记本电脑的示例输入文本。使用该文本调用 `full_chain`，并依次执行这两个步骤。最后，代码会打印出包含提取和格式化规格的最终结果——一个 JSON 字符串。

This Python code demonstrates how to use the LangChain library to process text. It utilizes two separate prompts: one to extract technical specifications from an input string and another to format these specifications into a JSON object. The ChatOpenAI model is employed for language model interactions, and the StrOutputParser ensures the output is in a usable string format. The LangChain Expression Language (LCEL) is used to elegantly chain these prompts and the language model together. The first chain, extraction_chain, extracts the specifications. The full_chain then takes the output of the extraction and uses it as input for the transformation prompt. A sample input text describing a laptop is provided. The full_chain is invoked with this text, processing it through both steps. The final result, a JSON string containing the extracted and formatted specifications, is then printed.

上下文工程和 提示工程

Context Engineering and Prompt Engineering

上下文工程（见图1）是一门系统性的学科，它旨在人工智能模型生成令牌之前，为其设计、构建并提供完整的上下文信息环境。该方法论认为，模型输出的质量与其说是取决于模型架构本身，不如说是取决于所提供上下文的丰富程度。

Context Engineering (see Fig.1) is the systematic discipline of designing, constructing, and delivering a complete informational environment to an AI model prior to token generation. This methodology asserts that the quality of a model's output is less dependent on the model's architecture itself and more on the richness of the context provided.

图 1： 上下文工程是为人工智能构建丰富、全面的信息环境的学科，因为上下文的质量是 实现高级智能体性能的主要因素。 

Fig.1:   Context Engineering is the discipline of building a rich, comprehensive informational environment for an AI, as the quality of this context  is a primary factor in enabling advanced Agentic performance.

它代表着对传统提示工程的重大革新，后者主要关注优化用户直接查询的措辞。上下文工程则扩展了这一范围，纳入了多层信息，例如 系统提示。系统提示 是一组定义人工智能运行参数的基础指令，例如 “您是一名技术文档撰写人员；您的语气必须正式且准确”。 上下文信息还会通过外部数据进一步丰富。这包括检索到的文档，人工智能会主动从知识库中获取信息以指导其响应，例如提取项目的技术规范。它还整合了工具输出，即人工智能使用外部 API 获取实时数据的结果，例如查询日历以确定用户的可用时间。这些显式数据与关键的隐式数据（例如用户身份、交互历史和环境状态）相结合。其核心原则是，即使是高级模型，如果对运行环境的了解有限或结构不完整，也会表现不佳。

It represents a significant evolution from traditional prompt engineering, which focuses primarily on optimizing the phrasing of a user's immediate query. Context Engineering expands this scope to include several layers of information, such as the system prompt , which is a foundational set of instructions defining the AI's operational parameters—for instance, "You are a technical writer; your tone must be formal and precise." The context is further enriched with external data. This includes retrieved documents, where the AI actively fetches information from a knowledge base to inform its response, such as pulling technical specifications for a project. It also incorporates tool outputs, which are the results from the AI using an external API to obtain real-time data, like querying a calendar to determine a user's availability. This explicit data is combined with critical implicit data, such as user identity, interaction history, and environmental state. The core principle is that even advanced models underperform when provided with a limited or poorly constructed view of the operational environment.

因此，这种做法将任务从单纯回答问题转变为为智能体构建全面的操作图景。例如，经过情境工程设计的智能体不仅会响应查询，还会首先整合用户的日程安排（工具输出）、与邮件收件人的专业关系（隐式数据）以及以往会议的记录（检索文档）。这使得模型能够生成高度相关、个性化且实用的输出。“工程”部分涉及创建强大的管道，以便在运行时获取和转换这些数据，并建立反馈循环以持续改进情境质量。

This practice, therefore, reframes the task from merely answering a question to building a comprehensive operational picture for the agent. For example, a context-engineered agent would not just respond to a query but would first integrate the user's calendar availability (a tool output), the professional relationship with an email's recipient (implicit data), and notes from previous meetings (retrieved documents). This allows the model to generate outputs that are highly relevant, personalized, and pragmatically useful. The "engineering" component involves creating robust pipelines to fetch and transform this data at runtime and establishing feedback loops to continually improve context quality.

为了实现这一点，可以使用专门的调优系统来大规模地自动化改进过程。例如，像谷歌的 Vertex AI 提示优化器这样的工具，可以通过系统地评估模型响应与一组示例输入和预定义的评估指标之间的关系来提升模型性能。这种方法能够有效地在不同模型之间调整提示和系统指令，而无需进行大量的手动重写。通过向此类优化器提供示例提示、系统指令和模板，它可以以编程方式优化上下文输入，从而为实现复杂上下文工程所需的反馈循环提供一种结构化的方法。

To implement this, specialized tuning systems can be used to automate the improvement process at scale. For example, tools like Google's Vertex AI prompt optimizer can enhance model performance by systematically evaluating responses against a set of sample inputs and predefined evaluation metrics. This approach is effective for adapting prompts and system instructions across different models without requiring extensive manual rewriting. By providing such an optimizer with sample prompts, system instructions, and a template, it can programmatically refine the contextual inputs, offering a structured method for implementing the feedback loops required for sophisticated Context Engineering.

这种结构化的方法正是区分初级人工智能工具和更复杂、更具情境感知能力的系统的关键所在。它将情境本身视为核心组成部分，高度重视智能体掌握的信息、获取信息的时间以及如何运用这些信息。这种做法确保模型能够全面理解用户的意图、历史记录和当前环境。最终，情境工程是推动无状态聊天机器人发展成为功能强大、具备情境感知能力的系统的关键方法。

This structured approach is what differentiates a rudimentary AI tool from a more sophisticated and contextually-aware system. It treats the context itself as a primary component, placing critical importance on what the agent knows, when it knows it, and how it uses that information. The practice ensures the model has a well-rounded understanding of the user's intent, history, and current environment. Ultimately, Context Engineering is a crucial methodology for advancing stateless chatbots into highly capable, situationally-aware systems.

概览

At a Glance

问题：  复杂任务在单一提示中处理时，往往会使逻辑学习模型（LLM）不堪重负，导致严重的性能问题。模型认知负荷的增加会提高出错的可能性，例如忽略指令、丢失上下文以及生成错误信息。单一的提示难以有效管理多个约束条件和顺序推理步骤。由于逻辑学习模型无法处理多方面请求的所有细节，因此会导致输出不可靠且不准确。

What:  Complex tasks often overwhelm LLMs when handled within a single prompt, leading to significant performance issues. The cognitive load on the model increases the likelihood of errors such as overlooking instructions, losing context, and generating incorrect information. A monolithic prompt struggles to manage multiple constraints and sequential reasoning steps effectively. This results in unreliable and inaccurate outputs, as the LLM fails to address all facets of the multifaceted request.

原因：  提示链通过将复杂问题分解为一系列相互关联的子任务，提供了一种标准化的解决方案。链中的每一步都使用一个聚焦的提示来执行特定操作，从而显著提高可靠性和可控性。一个提示的输出作为下一个提示的输入，形成一个逻辑工作流，逐步构建最终解决方案。这种模块化的分而治之策略使流程更易于管理、调试，并允许在各个步骤之间集成外部工具或结构化数据格式。这种模式是开发能够规划、推理和执行复杂工作流的复杂多步骤智能体系统的基础。

Why:  Prompt chaining provides a standardized solution by breaking down a complex problem into a sequence of smaller, interconnected sub-tasks. Each step in the chain uses a focused prompt to perform a specific operation, significantly improving reliability and control. The output from one prompt is passed as the input to the next, creating a logical workflow that progressively builds towards the final solution. This modular, divide-and-conquer strategy makes the process more manageable, easier to debug, and allows for the integration of external tools or structured data formats between steps. This pattern is foundational for developing sophisticated, multi-step Agentic systems that can plan, reason, and execute complex workflows.

经验法则：  当任务过于复杂而无法通过单个提示完成，涉及多个不同的处理阶段，需要在步骤之间与外部工具进行交互，或者构建需要执行多步骤推理并维护状态的智能体系统时，可以使用此模式。

Rule of thumb:  Use this pattern when a task is too complex for a single prompt, involves multiple distinct processing stages, requires interaction with external tools between steps, or when building Agentic systems that need to perform multi-step reasoning and maintain state.

可视化摘要  

Visual summary  

图 2：提示链模式： 代理接收来自用户的一系列提示，每个代理的输出作为链中下一个代理的输入。

Fig. 2: Prompt Chaining Pattern: Agents receive a series of prompts from the user, with the output of each agent serving as the input for the next in the chain.

要点总结

Key Takeaways

以下是一些关键要点：

Here are some key takeaways:

• 提示链式方法将复杂任务分解成一系列更小、更专注的步骤。 这种方法有时也被称为流水线模式。
• Prompt Chaining breaks down complex tasks into a sequence of smaller, focused steps. This is occasionally known as the Pipeline pattern.
• 链中的每一步都涉及 LLM 调用或处理逻辑，使用上一步的输出作为输入。
• Each step in a chain involves an LLM call or processing logic, using the output of the previous step as input.
• 这种模式提高了与语言模型进行复杂交互的可靠性和可管理性。
• This pattern improves the reliability and manageability of complex interactions with language models.
• LangChain/LangGraph 和 Google ADK 等框架提供了强大的工具来定义、管理和执行这些多步骤序列。
• Frameworks like LangChain/LangGraph, and Google ADK  provide robust tools to define, manage, and execute these multi-step sequences.

结论

Conclusion

通过将复杂问题分解为一系列更简单、更易于管理的子任务，提示链为指导大型语言模型提供了一个强大的框架。这种“分而治之”的策略通过让模型一次专注于一个特定的操作，显著提高了输出的可靠性和可控性。作为一种基础模式，它能够开发出具备多步骤推理、工具集成和状态管理能力的复杂人工智能代理。最终，掌握提示链对于构建能够执行远超单个提示所能处理的复杂工作流程的强大、上下文感知系统至关重要。

By deconstructing complex problems into a sequence of simpler, more manageable sub-tasks, prompt chaining provides a robust framework for guiding large language models. This "divide-and-conquer" strategy significantly enhances the reliability and control of the output by focusing the model on one specific operation at a time. As a foundational pattern, it enables the development of sophisticated AI agents capable of multi-step reasoning, tool integration, and state management. Ultimately, mastering prompt chaining is crucial for building robust, context-aware systems that can execute intricate workflows well beyond the capabilities of a single prompt.

参考

References

1. LangChain LCEL 文档： https://python.langchain.com/v0.2/docs/core_modules/expression_language/      
2. LangChain Documentation on LCEL: https://python.langchain.com/v0.2/docs/core_modules/expression_language/      
3. LangGraph 文档： https://langchain-ai.github.io/langgraph/
4. LangGraph Documentation: https://langchain-ai.github.io/langgraph/
5. 提示工程指南 - 提示链： https://www.promptingguide.ai/techniques/chaining    
6. Prompt Engineering Guide - Chaining Prompts: https://www.promptingguide.ai/techniques/chaining    
7. OpenAI API 文档（通用提示概念）： https://platform.openai.com/docs/guides/gpt/prompting  
8. OpenAI API Documentation (General Prompting Concepts): https://platform.openai.com/docs/guides/gpt/prompting  
9. 机组人员人工智能文档（任务和流程）： https://docs.crewai.com/    
10. Crew AI Documentation (Tasks and Processes): https://docs.crewai.com/    
11. Google AI for Developers（提示指南）： https://cloud.google.com/discover/what-is-prompt-engineering ?hl=en  
12. Google AI for Developers (Prompting Guides): https://cloud.google.com/discover/what-is-prompt-engineering?hl=en  
13. Vertex 提示优化器 https://cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/prompt-optimizer  
14. Vertex Prompt Optimizer https://cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/prompt-optimizer  

第二章：路由

Chapter 2: Routing

路由模式概述

Routing Pattern Overview

虽然通过提示链进行顺序处理是使用语言模型执行确定性线性工作流的基础技术，但其在需要自适应响应的场景中的适用性有限。现实世界中的智能体系统通常必须根据环境状态、用户输入或先前操作的结果等偶然因素，在多个潜在动作之间进行权衡。这种动态决策能力控制着流向不同专用功能、工具或子流程的进程，而路由机制正是实现这一能力的关键。

While sequential processing via prompt chaining is a foundational technique for executing deterministic, linear workflows with language models, its applicability is limited in scenarios requiring adaptive responses. Real-world agentic systems must often arbitrate between multiple potential actions based on contingent factors, such as the state of the environment, user input, or the outcome of a preceding operation. This capacity for dynamic decision-making, which governs the flow of control to different specialized functions, tools, or sub-processes, is achieved through a mechanism known as routing.

路由机制将条件逻辑引入到智能体的操作框架中，使其执行路径从固定不变转变为动态评估特定标准，并从一系列可能的后续动作中进行选择。这使得系统行为更加灵活，并能更好地感知上下文。

Routing introduces conditional logic into an agent's operational framework, enabling a shift from a fixed execution path to a model where the agent dynamically evaluates specific criteria to select from a set of possible subsequent actions. This allows for more flexible and context-aware system behavior.

例如，专为客户咨询设计的代理，如果配备了路由功能，可以首先对传入的查询进行分类，以确定用户的意图。基于此分类，它可以将查询定向 到专门的客服人员  进行直接问答、数据库检索工具用于查找账户信息，或用于处理复杂问题的升级流程，而不是默认使用单一的预设响应路径。 因此， 使用路由功能的更高级代理可以： 

For instance, an agent designed for customer inquiries, when equipped with a routing function, can first classify an incoming query to determine the user's intent. Based on this classification, it can then direct the query to a specialized agent  for direct question-answering, a database retrieval tool for account information, or an escalation procedure for complex issues, rather than defaulting to a single, predetermined response pathway.   Therefore, a  more sophisticated agent using routing could:

1. 分析用户查询。
2. Analyze the user's query.
3.  根据查询 意图 路由查询：
4. Route  the query based on its intent :

• 如果意图是“检查订单状态”，则路由到与订单数据库交互的子代理或工具链。
• If the intent is "check order status", route to a sub-agent or tool chain that interacts with the order database.
• 如果目的是“产品信息”，则路由至搜索产品目录的子代理商或连锁店。
• If the intent is "product information", route to a sub-agent or chain that searches the product catalog.
• 如果目的是“技术支持”，则转接到可以访问故障排除指南或升级到人工支持的其他流程。
• If the intent is "technical support", route to a different chain that accesses troubleshooting guides or escalates to a human.
• 如果意图不明确，则转接至澄清子代理或提示链。
• If the intent is unclear, route to a clarification sub-agent or prompt chain.

路由模式的核心组件是执行评估并指导流程的机制。该机制可以通过多种方式 实现 ：

The core component of the Routing pattern is a mechanism that performs the evaluation and directs the flow. This mechanism can be implemented in several  ways:

• 基于语言模型的路由：  语言模型本身可以被提示分析输入，并输出一个特定的标识符或指令，以指示下一步或目的地。例如，提示可以要求语言模型“分析以下用户查询，并仅输出类别：‘订单状态’、‘产品信息’、‘技术支持’或‘其他’”。然后，代理系统读取此输出并据此指导工作流程。
• LLM-based Routing:  The language model itself can be prompted to analyze the input and output a specific identifier or instruction that indicates the next step or destination. For example, a prompt might ask the LLM to "Analyze the following user query and output only the category: 'Order Status', 'Product Info', 'Technical Support', or 'Other'." The agentic system then reads this output and directs the workflow accordingly.
• 基于嵌入的路由：  输入查询可以转换为向量嵌入（参见 RAG，第 14 章）。然后，将此嵌入与表示不同路由或功能的嵌入进行比较。查询将被路由到嵌入最相似的路由。这对于语义路由非常有用，因为语义路由的决策基于输入的含义，而不仅仅是关键词。
• Embedding-based Routing:  The input query can be converted into a vector embedding (see RAG, Chapter 14). This embedding is then compared to embeddings representing different routes or capabilities. The query is routed to the route whose embedding is most similar. This is useful for semantic routing, where the decision is based on the meaning of the input rather than just keywords.
• 基于规则的路由： 这种 方法使用预定义的规则或逻辑（例如，if-else 语句、switch 语句），这些规则或逻辑基于从输入中提取的关键字、模式或结构化数据。与基于 LLM 的路由相比，这种方法速度更快、确定性更高， 但处理复杂或新颖的输入时灵活性较差。 
• Rule-based Routing:   This  involves using predefined rules or logic (e.g., if-else statements, switch cases) based on keywords, patterns, or structured data extracted from the input. This can be faster and more deterministic than LLM-based routing ,  but is less flexible for handling nuanced or novel inputs.
• 基于机器学习模型的 路由 ：它采用判别模型（例如分类器），该模型已在一小批带标签的数据集上进行专门训练，用于执行路由任务。虽然它与基于嵌入的方法在概念上存在相似之处，但其关键特征在于监督式微调过程，该过程会调整模型的参数以创建专门的路由功能。该技术与基于LLM的路由不同，因为其决策组件并非在推理时执行提示的生成模型。相反，路由逻辑编码在微调模型学习到的权重中。虽然LLM可用于预处理步骤以生成合成数据来扩充训练集，但它们 本身并不参与实时路由决策。
• Machine Learning Model -Based Routing : it employs a discriminative model, such as a classifier, that has been specifically trained on a small corpus of labeled data to perform a routing task. While it shares conceptual similarities with embedding-based methods, its key characteristic is the supervised fine-tuning process, which adjusts the model's parameters to create a specialized routing function. This technique is distinct from LLM-based routing because the decision-making component is not a generative model executing a prompt at inference time. Instead, the routing logic is encoded within the fine-tuned model's learned weights. While LLMs may be used in a pre-processing step to generate synthetic data for augmenting the training set, they are not involved in the real-time routing decision itself.

路由机制可以在代理的运行周期中的多个节点实施。它们可以在开始时应用以对主要任务进行分类，在处理链中的中间点应用以确定后续操作，或者在子程序期间应用以从给定的集合中选择最合适的工具。

Routing mechanisms can be implemented at multiple junctures within an agent's operational cycle. They can be applied at the outset to classify a primary task, at intermediate points within a processing chain to determine a subsequent action, or during a subroutine to select the most appropriate tool from a given set.

诸如 LangChain、LangGraph 和 Google 的 Agent Developer Kit (ADK) 等计算框架提供了用于定义和管理此类条件逻辑的显式结构。凭借其基于状态的图架构，LangGraph 特别适用于复杂的路由场景，在这些场景中，决策取决于整个系统的累积状态。类似地，Google 的 ADK 提供了用于构建代理能力和交互模型的基础组件，这些组件构成了实现路由逻辑的基础。在这些框架提供的执行环境中，开发人员可以定义可能的操作路径以及决定计算图中节点之间转换的函数或基于模型的评估。

Computational frameworks such as LangChain, LangGraph, and Google's Agent Developer Kit (ADK) provide explicit constructs for defining and managing such conditional logic. With its state-based graph architecture, LangGraph is particularly well-suited for complex routing scenarios where decisions are contingent upon the accumulated state of the entire system. Similarly, Google's ADK provides foundational components for structuring an agent's capabilities and interaction models, which serve as the basis for implementing routing logic. Within the execution environments provided by these frameworks, developers define the possible operational paths and the functions or model-based evaluations that dictate the transitions between nodes in the computational graph.

路由机制的实施 使系统能够超越确定性的顺序处理。它有助于开发更具适应性的执行流程，从而能够动态且适当地响应更广泛的输入和状态变化。

The implementation of routing enables a system to move beyond deterministic sequential processing. It facilitates the development of more adaptive execution flows that can respond dynamically and appropriately to a wider range of inputs and state changes.

实际应用及案例

Practical Applications & Use Cases

路由模式是自适应智能体系统设计中的关键控制机制，它使系统能够根据变化的输入和内部状态动态地改变执行路径。路由模式通过提供必要的条件逻辑层，在多个领域都具有实用价值。

The routing pattern is a critical control mechanism in the design of adaptive agentic systems, enabling them to dynamically alter their execution path in response to variable inputs and internal states. Its utility spans multiple domains by providing a necessary layer of conditional logic.

在人机交互中，例如与虚拟助手或人工智能驱动的辅导系统交互时，路由机制用于解读用户意图。对自然语言查询的初步分析会确定最合适的后续操作，例如调用特定的信息检索工具、转接人工客服，或根据用户表现选择课程中的下一个模块。这使得系统能够超越线性对话流程，并根据上下文做出响应。

In human-computer interaction, such as with virtual assistants or AI-driven tutors, routing is employed to interpret user intent. An initial analysis of a natural language query determines the most appropriate subsequent action, whether it is invoking a specific information retrieval tool, escalating to a human operator, or selecting the next module in a curriculum based on user performance. This allows the system to move beyond linear dialogue flows and respond contextually.

在自动化数据和文档处理流程中，路由扮演着分类和分发的角色。系统会根据内容、元数据或格式分析传入的数据，例如电子邮件、支持工单或 API 请求。然后，系统会将每个数据项定向到相应的工作流程，例如销售线索导入流程、针对 JSON 或 CSV 格式的特定数据转换功能，或紧急问题升级路径。

Within automated data and document processing pipelines, routing serves as a classification and distribution function. Incoming data, such as emails, support tickets, or API payloads, is analyzed based on content, metadata, or format. The system then directs each item to a corresponding workflow, such as a sales lead ingestion process, a specific data transformation function for JSON or CSV formats, or an urgent issue escalation path.

在涉及多个专用工具或代理的复杂系统中，路由机制扮演着高级调度器的角色。例如，一个由用于搜索、汇总和分析信息的不同代理组成的科研系统，会利用路由机制，根据当前目标将任务分配给最合适的代理。同样，人工智能编码助手也会利用路由机制来识别编程语言和用户的意图（例如调试、解释或翻译），然后再将代码片段传递给正确的专用工具。

In complex systems involving multiple specialized tools or agents, routing acts as a high-level dispatcher. A research system composed of distinct agents for searching, summarizing, and analyzing information would use a router to assign tasks to the most suitable agent based on the current objective. Similarly, an AI coding assistant uses routing to identify the programming language and user's intent—to debug, explain, or translate—before passing a code snippet to the correct specialized tool.

最终，路由提供了逻辑仲裁的能力，这对于创建功能多样化且具有上下文感知能力的系统至关重要。它将代理从预定义序列的静态执行者转变为能够在不断变化的条件下决策完成任务的最有效方法的动态系统。

Ultimately, routing provides the capacity for logical arbitration that is essential for creating functionally diverse and context-aware systems. It transforms an agent from a static executor of pre-defined sequences into a dynamic system that can make decisions about the most effective method for accomplishing a task under changing conditions.

动手实践代码示例（LangChain）

Hands-On Code Example (LangChain)

在代码中实现路由涉及定义所有可能的路径以及决定走哪条路径的逻辑。LangChain 和 LangGraph 等框架为此提供了特定的组件和结构。LangGraph 基于状态的图结构尤其便于可视化和实现路由逻辑。

Implementing routing in code involves defining the possible paths and the logic that decides which path to take. Frameworks like LangChain and LangGraph provide specific components and structures for this. LangGraph's state-based graph structure is particularly intuitive for visualizing and implementing routing logic.

这段代码演示了一个使用 LangChain 和 Google 生成式人工智能的简单类智能体系统。它设置了一个“协调器”，根据用户请求的意图（预​​订、信息或不明确）将请求路由到不同的模拟“子智能体”处理程序。该系统使用语言模型对请求进行分类，然后将其委托给相应的处理函数，模拟了多智能体架构中常见的基本委托模式。

This code demonstrates a simple agent-like system using LangChain and Google's Generative AI. It sets up a "coordinator" that routes user requests to different simulated "sub-agent" handlers based on the request's intent (booking, information, or unclear). The system uses a language model to classify the request and then delegates it to the appropriate handler function, simulating a basic delegation pattern often seen in multi-agent architectures.

首先，请确保已安装必要的库：

First, ensure you have the necessary libraries installed:

pip install langchain langgraph google-cloud-aiplatform langchain-google-genai google-adk deprecated pydantic

您还需要使用您选择的语言模型（例如 OpenAI、Google Gemini、Anthropic）的 API 密钥来设置您的环境。

You will also need to set up your environment with your API key for the language model you choose (e.g., OpenAI, Google Gemini, Anthropic).

# Copyright (c) 2025 Marco Fago # https://www.linkedin.com/in/marco-fago/ # # This code is licensed under the MIT License. # See the LICENSE file in the repository for the full license text. from langchain_google_genai import ChatGoogleGenerativeAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import RunnablePassthrough, RunnableBranch # --- Configuration --- # Ensure your API key environment variable is set (e.g., GOOGLE_API_KEY) try:    llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", temperature=0)    print(f"Language model initialized: {llm.model}") except Exception as e:    print(f"Error initializing language model: {e}")    llm = None # --- Define Simulated Sub-Agent Handlers (equivalent to ADK sub_agents) --- def booking_handler(request: str) -> str:    """Simulates the Booking Agent handling a request."""    print("\n--- DELEGATING TO BOOKING HANDLER ---")    return f"Booking Handler processed request: '{request}'. Result: Simulated booking action." def info_handler(request: str) -> str:    """Simulates the Info Agent handling a request."""    print("\n--- DELEGATING TO INFO HANDLER ---")    return f"Info Handler processed request: '{request}'. Result: Simulated information retrieval." def unclear_handler(request: str) -> str:    """Handles requests that couldn't be delegated."""    print("\n--- HANDLING UNCLEAR REQUEST ---")    return f"Coordinator could not delegate request: '{request}'. Please clarify." # --- Define Coordinator Router Chain (equivalent to ADK coordinator's instruction) --- # This chain decides which handler to delegate to. coordinator_router_prompt = ChatPromptTemplate.from_messages([    ("system", """Analyze the user's request and determine which specialist handler should process it.     - If the request is related to booking flights or hotels,       output 'booker'.     - For all other general information questions, output 'info'.     - If the request is unclear or doesn't fit either category,       output 'unclear'.     ONLY output one word: 'booker', 'info', or 'unclear'."""),    ("user", "{request}") ]) if llm:    coordinator_router_chain = coordinator_router_prompt | llm | StrOutputParser() # --- Define the Delegation Logic (equivalent to ADK's Auto-Flow based on sub_agents) --- # Use RunnableBranch to route based on the router chain's output. # Define the branches for the RunnableBranch branches = {    "booker": RunnablePassthrough.assign(output=lambda x: booking_handler(x['request']['request'])),    "info": RunnablePassthrough.assign(output=lambda x: info_handler(x['request']['request'])),    "unclear": RunnablePassthrough.assign(output=lambda x: unclear_handler(x['request']['request'])), } # Create the RunnableBranch. It takes the output of the router chain # and routes the original input ('request') to the corresponding handler. delegation_branch = RunnableBranch(    (lambda x: x['decision'].strip() == 'booker', branches["booker"]), # Added .strip()    (lambda x: x['decision'].strip() == 'info', branches["info"]),     # Added .strip()    branches["unclear"] # Default branch for 'unclear' or any other output ) # Combine the router chain and the delegation branch into a single runnable # The router chain's output ('decision') is passed along with the original input ('request') # to the delegation_branch. coordinator_agent = {    "decision": coordinator_router_chain,    "request": RunnablePassthrough() } | delegation_branch | (lambda x: x['output']) # Extract the final output # --- Example Usage --- def main():    if not llm:        print("\nSkipping execution due to LLM initialization failure.")        return    print("--- Running with a booking request ---")    request_a = "Book me a flight to London."    result_a = coordinator_agent.invoke({"request": request_a})    print(f"Final Result A: {result_a}")    print("\n--- Running with an info request ---")    request_b = "What is the capital of Italy?"    result_b = coordinator_agent.invoke({"request": request_b})    print(f"Final Result B: {result_b}")    print("\n--- Running with an unclear request ---")    request_c = "Tell me about quantum physics."    result_c = coordinator_agent.invoke({"request": request_c})    print(f"Final Result C: {result_c}") if __name__ == "__main__":    main()

如前所述，这段 Python 代码使用 LangChain 库和 Google 的生成式 AI 模型（具体来说是 gemini-2.5-flash）构建了一个简单的类代理系统。具体来说，它定义了三个模拟子代理处理器：booking_handler、info_handler 和 unknown_handler，每个处理器都用于处理特定类型的请求。

As mentioned, this Python code constructs a simple agent-like system using the LangChain library and Google's Generative AI model, specifically gemini-2.5-flash. In detail, It defines three simulated sub-agent handlers: booking_handler, info_handler, and unclear_handler, each designed to process specific types of requests.

核心组件是 coordinator_router_chain，它利用 ChatPromptTemplate 指示语言模型将传入的用户请求分类为三个类别之一：“预订”、“信息”或“不清楚”。然后，RunnableBranch 使用此路由链的输出将原始请求委托给相应的处理函数。RunnableBranch 检查语言模型的决策，并将请求数据定向到 booking_handler、info_handler 或 unknown_handler。coordinator_agent 将这些组件组合起来，首先路由请求以进行决策，然后将请求传递给选定的处理函数。最终输出从处理函数的响应中提取。

A core component is the coordinator_router_chain, which utilizes a ChatPromptTemplate to instruct the language model to categorize incoming user requests into one of three categories: 'booker', 'info', or 'unclear'. The output of this router chain is then used by a RunnableBranch to delegate the original request to the corresponding handler function. The RunnableBranch checks the decision from the language model and directs the request data to either the booking_handler, info_handler, or unclear_handler. The coordinator_agent combines these components, first routing the request for a decision and then passing the request to the chosen handler. The final output is extracted from the handler's response.

主函数通过三个示例请求演示了系统的使用方法，展示了模拟代理如何路由和处理不同的输入。为了确保系统的健壮性，代码中包含了语言模型初始化的错误处理机制。代码结构模拟了一个基本的多代理框架，其中中央协调器根据意图将任务委派给专门的代理。

The main function demonstrates the system's usage with three example requests, showcasing how different inputs are routed and processed by the simulated agents. Error handling for language model initialization is included to ensure robustness. The code structure mimics a basic multi-agent framework where a central coordinator delegates tasks to specialized agents based on intent.

动手实践代码示例（Google ADK）

Hands-On Code Example (Google ADK)

代理开发工具包 (ADK) 是一个用于构建代理系统的框架，它提供了一个结构化的环境来定义代理的 功能  和行为。与基于显式计算图的架构不同，ADK 范式中的路由通常是通过定义一组离散的“工具”来实现的，这些工具代表了代理的功能。框架的内部逻辑会根据用户查询选择合适的工具，该逻辑利用底层模型将用户意图与正确的功能处理程序进行匹配。

The Agent Development Kit (ADK) is a framework for engineering agentic systems, providing a structured environment for defining an agent's capabilities  and behaviours. In contrast to architectures based on explicit computational graphs, routing within the ADK paradigm is typically implemented by defining a discrete set of "tools" that represent the agent's functions. The selection of the appropriate tool in response to a user query is managed by the framework's internal logic, which leverages an underlying model to match user intent to the correct functional handler.

这段 Python 代码演示了一个使用 Google ADK 库的代理开发工具包 (ADK) 应用程序示例。它设置了一个名为“Coordinator”的代理，该代理根据预定义的指令将用户请求路由到专门的子代理（“Booker”用于预订，“Info”用于提供一般信息）。然后，子代理使用特定的工具来模拟处理请求，从而展示了代理系统中的基本委托模式。

This Python code demonstrates an example of an Agent Development Kit (ADK) application using Google's ADK library. It sets up a "Coordinator" agent that routes user requests to specialized sub-agents ("Booker" for bookings and "Info" for general information) based on defined instructions. The sub-agents then use specific tools to simulate handling the requests, showcasing a basic delegation pattern within an agent system

# Copyright (c) 2025 Marco Fago # # This code is licensed under the MIT License. # See the LICENSE file in the repository for the full license text. import uuid from typing import Dict, Any, Optional from google.adk.agents import Agent from google.adk.runners import InMemoryRunner from google.adk.tools import FunctionTool from google.genai import types from google.adk.events import Event # --- Define Tool Functions --- # These functions simulate the actions of the specialist agents. def booking_handler(request: str) -> str:    """    Handles booking requests for flights and hotels.    Args:        request: The user's request for a booking.    Returns:        A confirmation message that the booking was handled.    """    print("-------------------------- Booking Handler Called ----------------------------")    return f"Booking action for '{request}' has been simulated." def info_handler(request: str) -> str:    """    Handles general information requests.    Args:        request: The user's question.    Returns:        A message indicating the information request was handled.    """    print("-------------------------- Info Handler Called ----------------------------")    return f"Information request for '{request}'. Result: Simulated information retrieval." def unclear_handler(request: str) -> str:    """Handles requests that couldn't be delegated."""    return f"Coordinator could not delegate request: '{request}'. Please clarify." # --- Create Tools from Functions --- booking_tool = FunctionTool(booking_handler) info_tool = FunctionTool(info_handler) # Define specialized sub-agents equipped with their respective tools booking_agent = Agent(    name="Booker",    model="gemini-2.0-flash",    description="A specialized agent that handles all flight            and hotel booking requests by calling the booking tool.",    tools=[booking_tool] ) info_agent = Agent(    name="Info",    model="gemini-2.0-flash",    description="A specialized agent that provides general information       and answers user questions by calling the info tool.",    tools=[info_tool] ) # Define the parent agent with explicit delegation instructions coordinator = Agent(    name="Coordinator",    model="gemini-2.0-flash",    instruction=(        "You are the main coordinator. Your only task is to analyze         incoming user requests "        "and delegate them to the appropriate specialist agent.         Do not try to answer the user directly.\n"        "- For any requests related to booking flights or hotels,          delegate to the 'Booker' agent.\n"        "- For all other general information questions, delegate to the 'Info' agent."    ),    description="A coordinator that routes user requests to the      correct specialist agent.",    # The presence of sub_agents enables LLM-driven delegation (Auto-Flow) by default.    sub_agents=[booking_agent, info_agent] ) # --- Execution Logic --- async  def run_coordinator(runner: InMemoryRunner, request: str):    """Runs the coordinator agent with a given request and delegates."""    print(f"\n--- Running Coordinator with request: '{request}' ---")    final_result = ""    try:        user_id = "user_123"        session_id = str(uuid.uuid4())        await  runner.session_service.create_session(            app_name=runner.app_name, user_id=user_id, session_id=session_id        )        for event in runner.run(            user_id=user_id,            session_id=session_id,            new_message=types.Content(                role='user',                parts=[types.Part(text=request)]            ),        ):            if event.is_final_response() and event.content:                # Try to get text directly from event.content                # to avoid iterating parts                if hasattr(event.content, 'text') and event.content.text:                     final_result = event.content.text                elif event.content.parts:                    # Fallback: Iterate through parts and extract text (might trigger warning)                    text_parts = [part.text for part in event.content.parts if part.text]                    final_result = "".join(text_parts)                # Assuming the loop should break after the final response                break        print(f"Coordinator Final Response: {final_result}")        return final_result    except Exception as e:        print(f"An error occurred while processing your request: {e}")        return f"An error occurred while processing your request: {e}" async  def main():    """Main function to run the ADK example."""    print("--- Google ADK Routing Example (ADK Auto-Flow Style) ---")    print("Note: This requires Google ADK installed and authenticated.")    runner = InMemoryRunner(coordinator)    # Example Usage    result_a = await run_coordinator(runner, "Book me a hotel in Paris.")    print(f"Final Output A: {result_a}")    result_b = await run_coordinator(runner, "What is the highest mountain in the world?")    print(f"Final Output B: {result_b}")    result_c = await run_coordinator(runner, "Tell me a random fact.") # Should go to Info    print(f"Final Output C: {result_c}")    result_d = await run_coordinator(runner, "Find flights to Tokyo next month.") # Should go to Booker    print(f"Final Output D: {result_d}") if __name__ == "__main__":    import nest_asyncio    nest_asyncio.apply()    await main()

该脚本包含一个主协调器代理和两个专门的子代理：预订器和信息代理。每个专门代理都配备了一个 FunctionTool，该工具封装了一个模拟操作的 Python 函数。预订处理程序函数模拟处理航班和酒店预订，而信息处理程序函数模拟检索一般信息。虽然当前协调器逻辑在主运行协调器函数中并未显式地在委托失败时使用它，但仍然包含了一个不明确的处理程序作为协调器无法委托请求的备用方案。

This script consists of a main Coordinator agent and two specialized sub_agents: Booker and Info. Each specialized agent is equipped with a FunctionTool that wraps a Python function simulating an action. The booking_handler function simulates handling flight and hotel bookings, while the info_handler function simulates retrieving general information. The unclear_handler is included as a fallback for requests the coordinator cannot delegate, although the current coordinator logic doesn't explicitly use it for delegation failure in the main run_coordinator function.

根据其指令定义，协调器代理的主要职责是分析传入的用户消息，并将其委托给 Booker 代理或 Info 代理。由于协调器代理定义了子代理，因此这种委托由 ADK 的自动流机制自动处理。`run_coordinator` 函数会设置一个内存运行器 (InMemoryRunner)，创建用户 ID 和会话 ID，然后使用该运行器通过协调器代理处理用户的请求。`runner.run` 方法处理请求并生成事件，代码会从 `event.content` 中提取最终响应文本。

The Coordinator agent's primary role, as defined in its instruction, is to analyze incoming user messages and delegate them to either the Booker or Info agent. This delegation is handled automatically by the ADK's Auto-Flow mechanism because the Coordinator has sub_agents defined. The run_coordinator function sets up an InMemoryRunner, creates a user and session ID, and then uses the runner to process the user's request through the coordinator agent. The runner.run method processes the request and yields events, and the code extracts the final response text from the event.content.

主要功能通过运行协调器并执行不同的请求来演示系统的使用方法，展示了它如何将预订请求委派给预订员，将信息请求委派给信息代理。

The main function demonstrates the system's usage by running the coordinator with different requests, showcasing how it delegates booking requests to the Booker and information requests to the Info agent.

概览

At a Glance

问题 ： 智能体系统通常需要响应各种各样的输入和情况，而这些无法通过单一的线性流程来处理。简单的顺序工作流缺乏基于上下文进行决策的能力。如果没有机制来为特定任务选择正确的工具或子流程，系统就会变得僵化且缺乏适应性。这种局限性使得构建能够应对现实世界用户请求的复杂性和多变性的复杂应用程序变得困难。

What : Agentic systems must often respond to a wide variety of inputs and situations that cannot be handled by a single, linear process. A simple sequential workflow lacks the ability to make decisions based on context. Without a mechanism to choose the correct tool or sub-process for a specific task, the system remains rigid and non-adaptive. This limitation makes it difficult to build sophisticated applications that can manage the complexity and variability of real-world user requests.

原因： 路由模式通过在代理的操作框架中引入条件逻辑，提供了一种标准化的解决方案。它使系统能够首先分析传入的查询，以确定其意图或性质。基于此分析，代理可以动态地将控制流导向最合适的专用工具、功能或子代理。此决策可以通过多种方法驱动，包括提示逻辑逻辑模型 (LLM)、应用预定义规则或使用基于嵌入的语义相似性。最终，路由将静态的、预定的执行路径转换为灵活且上下文感知的工作流程，从而能够选择最佳操作。 

Why:   The Routing pattern provides a standardized solution by introducing conditional logic into an agent's operational framework. It enables the system to first analyze an incoming query to determine its intent or nature. Based on this analysis, the agent dynamically directs the flow of control to the most appropriate specialized tool, function, or sub-agent. This decision can be driven by various methods, including prompting LLMs, applying predefined rules, or using embedding-based semantic similarity. Ultimately, routing transforms a static, predetermined execution path into a flexible and context-aware workflow capable of selecting the best possible action.

经验法则： 当代理需要根据用户输入或当前状态在多个不同的工作流程、工具或子代理之间做出选择时，应使用路由模式。对于需要对传入请求进行分类或分流以处理不同类型任务的应用程序而言，路由模式至关重要，例如客户支持机器人需要区分销售咨询、技术支持和账户管理问题。 

Rule of Thumb:   Use the Routing pattern when an agent must decide between multiple distinct workflows, tools, or sub-agents based on the user's input or the current state. It is essential for applications that need to triage or classify incoming requests to handle different types of tasks, such as a customer support bot distinguishing between sales inquiries, technical support, and account management questions.

视觉摘要：

Visual Summary:

图1：使用LLM作为路由器的路由器布局图

Fig.1: Router pattern, using an LLM as a Router

要点总结

Key Takeaways

• 路由使代理能够根据条件动态地决定工作流程中的下一步。
• Routing enables agents to make dynamic decisions about the next step in a workflow based on conditions.
• 它允许智能体处理各种输入并调整其行为，超越线性执行。
• It allows agents to handle diverse inputs and adapt their behavior, moving beyond linear execution.
• 路由逻辑可以使用 LLM、基于规则的系统或嵌入相似性来实现。
• Routing logic can be implemented using LLMs, rule-based systems, or embedding similarity.
• LangGraph 和 Google ADK 等框架提供了结构化的方式来定义和管理代理工作流中的路由，尽管它们的架构方法有所不同。
• Frameworks like LangGraph and Google ADK provide structured ways to define and manage routing within agent workflows, albeit with different architectural approaches.

结论

Conclusion

路由模式是构建真正动态且响应迅速的智能体系统的关键步骤。通过实现路由，我们超越了简单的线性执行流程，使智能体能够就如何处理信息、响应用户输入以及利用可用工具或子智能体做出智能决策。

The Routing pattern is a critical step in building truly dynamic and responsive agentic systems. By implementing routing, we move beyond simple, linear execution flows and empower our agents to make intelligent decisions about how to process information, respond to user input, and utilize available tools or sub-agents.

我们已经了解了路由技术在各个领域的应用，从客户服务聊天机器人到复杂的数据处理流程。分析输入并根据条件引导工作流程的能力，对于创建能够应对现实世界任务固有变化性的智能体至关重要。

We've seen how routing can be applied in various domains, from customer service chatbots to complex data processing pipelines. The ability to analyze input and conditionally direct the workflow is fundamental to creating agents that can handle the inherent variability of real-world tasks.

使用Lang Chain和 Google ADK 的 代码示例 展示了两种不同但同样有效的路由实现方法。LangGraph 基于图的结构提供了一种直观且明确的方式来定义状态和转换，使其成为具有复杂路由逻辑的多步骤工作流的理想选择。另一方面，Google ADK 通常侧重于定义不同的功能（工具），并依赖于框架将用户请求路由到相应工具处理程序的能力，这对于具有明确定义的一组离散操作的代理来说可能更简单。

The code examples using Lang Chain  and Google ADK demonstrate two different, yet effective, approaches to implementing routing. LangGraph's graph-based structure provides a visual and explicit way to define states and transitions, making it ideal for complex, multi-step workflows with intricate routing logic. Google ADK, on the other hand, often focuses on defining distinct capabilities (Tools) and relies on the framework's ability to route user requests to the appropriate tool handler, which can be simpler for agents with a well-defined set of discrete actions.

掌握路由模式对于构建能够智能应对不同场景并根据上下文提供定制化响应或操作的智能体至关重要。它是创建功能全面且稳健的智能体应用程序的关键组成部分。

Mastering the Routing pattern is essential for building agents that can intelligently navigate different scenarios and provide tailored responses or actions based on context. It's a key component in creating versatile and robust agentic applications.

参考

References

1. LangGraph 文档： https://www.langchain.com/    
2. LangGraph Documentation: https://www.langchain.com/    
3. Google Agent 开发者工具包文档： https://google.github.io/adk-docs/  
4. Google Agent Developer Kit Documentation: https://google.github.io/adk-docs/  

第三章：并行化

Chapter 3: Parallelization

并行化模式概述

Parallelization Pattern Overview

在前几章中，我们探讨了用于顺序工作流的提示链模式和用于动态决策以及不同路径之间转换的路由模式。虽然这些模式至关重要，但许多复杂的智能体任务涉及多个子任务，这些子任务可以 同时执行  ，而不是按顺序执行。这时， 并行化  模式就显得尤为重要。

In the previous chapters, we've explored Prompt Chaining for sequential workflows and Routing for dynamic decision-making and transitions between different paths. While these patterns are essential, many complex agentic tasks involve multiple sub-tasks that can be executed simultaneously  rather than one after another. This is where the Parallelization  pattern becomes crucial.

并行化是指同时执行多个组件，例如 LLM 调用、工具使用，甚至是整个子代理 （见图 1） 。并行执行无需等待一个步骤完成即可开始下一个步骤，它允许独立任务同时运行，从而显著缩短可分解为独立部分的任务的整体执行时间。

Parallelization involves executing multiple components, such as LLM calls, tool usages, or even entire sub-agents, concurrently (see Fig.1) . Instead of waiting for one step to complete before starting the next, parallel execution allows independent tasks to run at the same time, significantly reducing the overall execution time for tasks that can be broken down into independent parts.

考虑一个旨在研究某个主题并总结研究结果的智能体。一种循序渐进的方法可能是：

Consider an agent designed to research a topic and summarize its findings. A sequential approach might:

1. 查找来源 A。
2. Search for Source A.
3. 总结资料A。
4. Summarize Source A.
5. 查找来源 B。
6. Search for Source B.
7. 总结资料B。
8. Summarize Source B.
9. 综合摘要 A 和 B 得出最终答案。
10. Synthesize a final answer from summaries A and B.

另一种并行方法是：

A parallel approach could instead:

1. 同时搜索资源 A 和  资源 B。
2. Search for Source A and  Search for Source B simultaneously.
3. 两个搜索完成后，同时对来源 A 和  来源 B 进行汇总。
4. Once both searches are complete, Summarize Source A and  Summarize Source B simultaneously.
5. 根据摘要 A 和 B 综合得出最终答案（此步骤通常是顺序进行的，需要等待并行步骤完成后再进行）。
6. Synthesize a final answer from summaries A and B (this step is typically sequential, waiting for the parallel steps to finish).

其核心思想是识别工作流程中不依赖于其他部分输出的部分，并并行执行这些部分。这在处理存在延迟的外部服务（例如 API 或数据库）时尤为有效，因为您可以同时发出多个请求。

The core idea is to identify parts of the workflow that do not depend on the output of other parts and execute them in parallel. This is particularly effective when dealing with external services (like APIs or databases) that have latency, as you can issue multiple requests concurrently.

实现并行化通常需要支持异步执行或多线程/多进程的框架。现代代理框架在设计时就考虑到了异步操作，因此您可以轻松定义可以并行运行的步骤。

Implementing parallelization often requires frameworks that support asynchronous execution or multi-threading/multi-processing. Modern agentic frameworks are designed with asynchronous operations in mind, allowing you to easily define steps that can run in parallel.

图1. 子代理并行化示例

Fig.1. Example of parallelization with sub-agents

LangChain 、LangGraph 和 Google ADK 等框架 提供了并行执行机制。在 LangChain 表达式语言 (LCEL) 中，您可以通过使用诸如 |（表示顺序）之类的运算符组合可运行对象，以及通过构建链或图的结构使其包含可并发执行的分支来实现并行执行。LangGraph 的图结构允许您定义多个节点，这些节点可以从单个状态转换中执行，从而有效地在工作流中实现并行分支。Google ADK 提供了强大的原生机制来促进和管理代理的并行执行，从而显著提高复杂多代理系统的效率和可扩展性。ADK 框架的这种固有功能使开发人员能够设计和实现多个代理可以并发而非顺序运行的解决方案。 

Frameworks like LangChai n, LangGraph, and Google ADK  provide mechanisms for parallel execution. In LangChain Expression Language (LCEL), you can achieve parallel execution by combining runnable objects using operators like | (for sequential) and by structuring your chains or graphs to have branches that execute concurrently. LangGraph, with its graph structure, allows you to define multiple nodes that can be executed from a single state transition, effectively enabling parallel branches in the workflow. Google ADK provides robust, native mechanisms to facilitate and manage the parallel execution of agents, significantly enhancing the efficiency and scalability of complex, multi-agent systems.   This inherent capability within the ADK framework allows developers to design and implement solutions where multiple agents can operate concurrently, rather than sequentially.

并行化模式对于提升智能体系统的效率和响应速度至关重要，尤其是在处理涉及多次独立查找、计算或与外部服务交互的任务时。它是优化复杂智能体工作流程性能的关键技术。

The Parallelization pattern is vital for improving the efficiency and responsiveness of agentic systems, especially when dealing with tasks that involve multiple independent lookups, computations, or interactions with external services. It's a key technique for optimizing the performance of complex agent workflows.

实际应用及案例

Practical Applications & Use Cases

并行化是一种强大的模式，可用于优化各种应用程序中的代理性能：

Parallelization is a powerful pattern for optimizing agent performance across various applications:

1. 信息收集与研究：

1. Information Gathering and Research:

同时从多个来源收集信息是一个经典的应用场景。

Collecting information from multiple sources simultaneously is a classic use case.

• 使用案例：  代理人对公司进行调研。
• Use Case:  An agent researching a company.

• 并行任务：  同时搜索新闻文章、提取股票数据、检查社交媒体提及和查询公司数据库。
• Parallel Tasks:  Search news articles, pull stock data, check social media mentions, and query a company database, all at the same time.
• 优点：  比顺序查找更快地获取全面信息。
• Benefit:  Gathers a comprehensive view much faster than sequential lookups.

2. 数据处理与分析：

2. Data Processing and Analysis:

同时应用不同的分析技术或处理不同的数据段。

Applying different analysis techniques or processing different data segments concurrently.

• 使用案例：  代理分析客户反馈。
• Use Case:  An agent analyzing customer feedback.

• 并行任务：  同时对一批反馈条目进行情感分析、提取关键词、对反馈进行分类并识别紧急问题。
• Parallel Tasks:  Run sentiment analysis, extract keywords, categorize feedback, and identify urgent issues simultaneously across a batch of feedback entries.
• 优点：  可快速提供多方面的分析。
• Benefit:  Provides a multi-faceted analysis quickly.

3. 多 API 或工具交互：

3. Multi-API or Tool Interaction:

调用多个独立的 API 或工具来收集不同类型的信息或执行不同的操作。

Calling multiple independent APIs or tools to gather different types of information or perform different actions.

• 使用案例：  旅行规划代理。
• Use Case:  A travel planning agent.

• 并行任务：  同时查看航班价格、搜索酒店空房情况、查找当地活动和查找餐厅推荐。
• Parallel Tasks:  Check flight prices, search for hotel availability, look up local events, and find restaurant recommendations concurrently.
• 优点：  更快地提供完整的旅行计划。
• Benefit:  Presents a complete travel plan faster.

4. 多组件内容生成：

4. Content Generation with Multiple Components:

同时生成复杂内容的各个部分。

Generating different parts of a complex piece of content in parallel.

• 使用场景：  代理商创建营销邮件。
• Use Case:  An agent creating a marketing email.

• 同时执行以下任务：  生成邮件主题、撰写邮件正文、查找相关图片并创建号召性用语按钮文本。
• Parallel Tasks:  Generate a subject line, draft the email body, find a relevant image, and create a call-to-action button text simultaneously.
• 优点：  能更高效地组装最终邮件。
• Benefit:  Assembles the final email more efficiently.

5. 验证与确认：

5. Validation and Verification:

同时执行多个独立的检查或验证。

Performing multiple independent checks or validations concurrently.

• 使用场景：  代理验证用户输入。
• Use Case:  An agent verifying user input.

• 并行任务：  同时检查电子邮件格式、验证电话号码、根据数据库验证地址，并检查是否存在不雅用语。
• Parallel Tasks:  Check email format, validate phone number, verify address against a database, and check for profanity simultaneously.
• 优点：  能更快地反馈输入的有效性。
• Benefit:  Provides faster feedback on input validity.

6. 多模态处理：

6. Multi-Modal Processing:

同时处理同一输入的不同模态（文本、图像、音频）。

Processing different modalities (text, image, audio) of the same input concurrently.

• 使用案例：  代理分析包含文本和图像的社交媒体帖子。
• Use Case:  An agent analyzing a social media post with text and an image.

• 并行任务：同时  分析文本的情感和关键词 ，并  分析图像中的物体和场景描述。
• Parallel Tasks:  Analyze the text for sentiment and keywords and  analyze the image for objects and scene description simultaneously.
• 优势：  更快地整合来自不同模式的信息。
• Benefit:  Integrates insights from different modalities more quickly.

7. A/B 测试或多选项生成：

7. A/B Testing or Multiple Options Generation:

并行生成多个响应或输出变体，以选择最佳变体。

Generating multiple variations of a response or output in parallel to select the best one.

• 使用案例：  一个代理程序生成不同的创意文本选项。
• Use Case:  An agent generating different creative text options.

• 并行任务：  使用略有不同的提示或模型，同时为一篇文章生成三个不同的标题。
• Parallel Tasks:  Generate three different headlines for an article simultaneously using slightly different prompts or models.
• 优点：  可以快速比较和选择最佳方案。
• Benefit:  Allows for quick comparison and selection of the best option.

并行化是智能体设计中的一项基本优化技术，它允许开发人员利用独立任务的并发执行来构建性能更高、响应更快的应用程序。

Parallelization is a fundamental optimization technique in agentic design, allowing developers to build more performant and responsive applications by leveraging concurrent execution for independent tasks.

动手实践代码示例（ LangChain ）

Hands-On Code Example ( LangChain )

LangChain框架内的并行执行由LangChain表达式语言（LCEL）实现。其主要方法是将多个可运行组件组织成字典或列表结构。当此集合作为输入传递给链中的后续组件时，LCEL运行时会并发执行其中包含的可运行组件。

Parallel execution within the LangChain framework is facilitated by the LangChain Expression Language (LCEL). The primary method involves structuring multiple runnable components within a dictionary or list construct. When this collection is passed as input to a subsequent component in the chain, the LCEL runtime executes the contained runnables concurrently.

在 LangGraph 的上下文中，这一原则应用于图的拓扑结构。并行工作流通过构建图的结构来实现，使得多个缺乏直接顺序依赖关系的节点可以从同一个公共节点启动。这些并行路径独立执行，之后它们的结果可以在图中的后续汇聚点进行聚合。

In the context of LangGraph, this principle is applied to the graph's topology. Parallel workflows are defined by architecting the graph such that multiple nodes, lacking direct sequential dependencies, can be initiated from a single common node. These parallel pathways execute independently before their results can be aggregated at a subsequent convergence point in the graph.

以下实现展示了使用 LangChain 框架构建的并行处理工作流。该工作流旨在响应单个用户查询，并发执行两个独立的操作。这些并行进程被实例化为不同的链或函数，它们的各自输出随后被聚合为一个统一的结果。

The following implementation demonstrates a parallel processing workflow constructed with the LangChain framework. This workflow is designed to execute two independent operations concurrently in response to a single user query. These parallel processes are instantiated as distinct chains or functions, and their respective outputs are subsequently aggregated into a unified result.

此实现的前提条件包括安装必要的 Python 包，例如 langchain、langchain-community 以及模型提供程序库（例如 langchain-openai）。此外，还必须在本地环境中配置所选语言模型的有效 API 密钥以进行身份​​验证。

The prerequisites for this implementation include the installation of the requisite Python packages, such as langchain, langchain-community, and a model provider library like langchain-openai. Furthermore, a valid API key for the chosen language model must be configured in the local environment for authentication.

import os import asyncio from typing import Optional from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from langchain_core.runnables import Runnable, RunnableParallel, RunnablePassthrough # --- Configuration --- # Ensure your API key environment variable is set (e.g., OPENAI_API_KEY) try:    llm: Optional[ChatOpenAI] = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)   except Exception as e:    print(f"Error initializing language model: {e}")    llm = None # --- Define Independent Chains --- # These three chains represent distinct tasks that can be executed in parallel. summarize_chain: Runnable = (    ChatPromptTemplate.from_messages([        ("system", "Summarize the following topic concisely:"),        ("user", "{topic}")    ])    | llm    | StrOutputParser() ) questions_chain: Runnable = (    ChatPromptTemplate.from_messages([        ("system", "Generate three interesting questions about the following topic:"),        ("user", "{topic}")    ])    | llm    | StrOutputParser() ) terms_chain: Runnable = (    ChatPromptTemplate.from_messages([        ("system", "Identify 5-10 key terms from the following topic, separated by commas:"),        ("user", "{topic}")    ])    | llm    | StrOutputParser() ) # --- Build the Parallel + Synthesis Chain --- # 1. Define the block of tasks to run in parallel. The results of these, #    along with the original topic, will be fed into the next step. map_chain = RunnableParallel(    {        "summary": summarize_chain,        "questions": questions_chain,        "key_terms": terms_chain,        "topic": RunnablePassthrough(),  # Pass the original topic through    } ) # 2. Define the final synthesis prompt which will combine the parallel results. synthesis_prompt = ChatPromptTemplate.from_messages([    ("system", """Based on the following information:     Summary: {summary}     Related Questions: {questions}     Key Terms: {key_terms}     Synthesize a comprehensive answer."""),    ("user", "Original topic: {topic}") ]) # 3. Construct the full chain by piping the parallel results directly #    into the synthesis prompt, followed by the LLM and output parser. full_parallel_chain = map_chain | synthesis_prompt | llm | StrOutputParser() # --- Run the Chain --- async def run_parallel_example(topic: str) -> None:    """    Asynchronously invokes the parallel processing chain with a specific topic    and prints the synthesized result.    Args:        topic: The input topic to be processed by the LangChain chains.    """    if not llm:        print("LLM not initialized. Cannot run example.")        return    print(f"\n--- Running Parallel LangChain Example for Topic: '{topic}' ---")    try:        # The input to `ainvoke` is the single 'topic' string,        # then passed to each runnable in the `map_chain`.        response = await full_parallel_chain.ainvoke(topic)        print("\n--- Final Response ---")        print(response)    except Exception as e:        print(f"\nAn error occurred during chain execution: {e}") if __name__ == "__main__":    test_topic = "The history of space exploration"    # In Python 3.7+, asyncio.run is the standard way to run an async function.    asyncio.run(run_parallel_example(test_topic))

提供的 Python 代码实现了一个 LangChain 应用，旨在利用并行执行高效地处理给定主题。请注意， asyncio 提供的是 并发 ，而非并行。它通过使用事件循环在单个线程上实现并行，该事件循环会在某个任务空闲时（例如，等待网络请求）智能地切换到其他任务。这营造出多个任务同时执行的效果，但代码本身仍然由单个线程执行，并受到 Python 全局解释器锁 (GIL) 的限制。  

The provided Python code implements a LangChain application designed for processing a given topic efficiently by leveraging parallel execution. Note that asyncio provides concurrency , not parallelism. It achieves this on a single thread by using an event loop that intelligently switches between tasks when one is idle (e.g., waiting for a network request). This creates the effect of multiple tasks progressing at once, but the code itself is still being executed by only one thread, constrained by Python's Global Interpreter Lock (GIL).  

代码首先从 langchain_openai  和 langchain_core导入必要的模块 ，包括语言模型、提示、输出解析和可运行结构等组件。代码尝试初始化一个 ChatOpenAI  实例，具体使用的是“gpt-4o-mini”模型，并指定了控制创造力的温度。在语言模型初始化过程中，使用 try-except 块来增强鲁棒性。然后定义了三个独立的 LangChain“链”，每个链都针对输入主题执行不同的任务。第一个链用于简洁地概括主题，使用系统消息和包含主题占位符的用户消息。第二个链配置为生成三个与主题相关的有趣问题。第三个链用于从输入主题中识别 5 到 10 个关键词，并要求它们以逗号分隔。每个独立的链都包含一个针对其特定任务定制的 ChatPromptTemplate  ，后面是已初始化的语言模型和一个  用于将输出格式化为字符串的StrOutputParser 。

The code begins by importing essential modules from langchain_openai  and langchain_core , including components for language models, prompts, output parsing, and runnable structures. The code attempts to initialize a ChatOpenAI  instance, specifically using the "gpt-4o-mini" model, with a specified temperature for controlling creativity. A try-except block is used for robustness during the language model initialization. Three independent LangChain "chains" are then defined, each designed to perform a distinct task on the input topic. The first chain is for summarizing the topic concisely, using a system message and a user message containing the topic placeholder. The second chain is configured to generate three interesting questions related to the topic. The third chain is set up to identify between 5 and 10 key terms from the input topic, requesting them to be comma-separated. Each of these independent chains consists of a ChatPromptTemplate  tailored to its specific task, followed by the initialized language model and a StrOutputParser  to format the output as a string.

 然后构建一个RunnableParallel模块，将这三个链捆绑在一起，使它们能够同时执行。这个并行可运行程序还包含一个 RunnablePassthrough  ，以确保原始输入主题可供后续步骤使用。为最终的综合步骤定义了一个单独的ChatPromptTemplate  ，它以摘要、问题、关键词和原始主题作为输入，生成一个完整的答案。完整的端到端处理链，名为full_parallel_chain ，是通过将map_chain  （并行模块）按顺序插入综合提示符，然后是语言模型和输出解析器而创建的。提供了一个异步函数run_parallel_example 来演示如何调用full_parallel_chain 。该函数以主题作为输入，并使用invoke 来运行异步链。最后，标准的 Python if __name__ == "__main__": 模块展示了如何使用示例主题（在本例中为“太空探索的历史”）来执行run_parallel_example  ，并使用asyncio.run 来管理异步执行。

A RunnableParallel  block is then constructed to bundle these three chains, allowing them to execute simultaneously. This parallel runnable also includes a RunnablePassthrough  to ensure the original input topic is available for subsequent steps. A separate ChatPromptTemplate  is defined for the final synthesis step, taking the summary, questions, key terms, and the original topic as input to generate a comprehensive answer. The full end-to-end processing chain, named full_parallel_chain , is created by sequencing the map_chain  (the parallel block) into the synthesis prompt, followed by the language model and the output parser. An asynchronous function run_parallel_example  is provided to demonstrate how to invoke this full_parallel_chain . This function takes the topic as input and uses invoke  to run the asynchronous chain. Finally, the standard Python if __name__ == "__main__":  block shows how to execute the run_parallel_example  with a sample topic, in this case, "The history of space exploration", using asyncio.run  to manage the asynchronous execution.

本质上，这段代码建立了一个工作流程，其中针对给定主题同时执行多个 LLM 调用（用于摘要、提问和术语检索），然后通过最终的 LLM 调用将它们的结果合并。这展示了使用 LangChain 在智能体工作流程中实现并行化的核心思想。

In essence, this code sets up a workflow where multiple LLM calls (for summarizing, questions, and terms) happen at the same time for a given topic, and their results are then combined by a final LLM call. This showcases the core idea of parallelization in an agentic workflow using LangChain.

动手实践代码示例（Google ADK）

Hands-On Code Example (Google ADK)

好的，现在让我们来看一个具体的例子，用 Google ADK 框架来阐释这些概念。我们将探讨如何应用 ADK 原语（例如 ParallelAgent 和 SequentialAgent）来构建代理流程，从而利用并发执行来提高效率。

Okay, let's now turn our attention to a concrete example illustrating these concepts within the Google ADK framework. We'll examine how the ADK primitives, such as ParallelAgent and SequentialAgent, can be applied to build an agent flow that leverages concurrent execution for improved efficiency.

from google.adk.agents import LlmAgent, ParallelAgent, SequentialAgent from google.adk.tools import google_search GEMINI_MODEL="gemini-2.0-flash" # --- 1. Define Researcher Sub-Agents (to run in parallel) --- # Researcher 1: Renewable Energy researcher_agent_1 = LlmAgent(     name="RenewableEnergyResearcher",     model=GEMINI_MODEL,     instruction="""You are an AI Research Assistant specializing in energy. Research the latest advancements in 'renewable energy sources'. Use the Google Search tool provided. Summarize your key findings concisely (1-2 sentences). Output *only* the summary. """,     description="Researches renewable energy sources.",     tools=[google_search],     # Store result in state for the merger agent     output_key="renewable_energy_result" ) # Researcher 2: Electric Vehicles researcher_agent_2 = LlmAgent(     name="EVResearcher",     model=GEMINI_MODEL,     instruction="""You are an AI Research Assistant specializing in transportation. Research the latest developments in 'electric vehicle technology'. Use the Google Search tool provided. Summarize your key findings concisely (1-2 sentences). Output *only* the summary. """,     description="Researches electric vehicle technology.",     tools=[google_search],     # Store result in state for the merger agent     output_key="ev_technology_result" ) # Researcher 3: Carbon Capture researcher_agent_3 = LlmAgent(     name="CarbonCaptureResearcher",     model=GEMINI_MODEL,     instruction="""You are an AI Research Assistant specializing in climate solutions. Research the current state of 'carbon capture methods'. Use the Google Search tool provided. Summarize your key findings concisely (1-2 sentences). Output *only* the summary. """,     description="Researches carbon capture methods.",     tools=[google_search],     # Store result in state for the merger agent     output_key="carbon_capture_result" ) # --- 2. Create the ParallelAgent (Runs researchers concurrently) --- # This agent orchestrates the concurrent execution of the researchers. # It finishes once all researchers have completed and stored their results in state. parallel_research_agent = ParallelAgent(     name="ParallelWebResearchAgent",     sub_agents=[researcher_agent_1, researcher_agent_2, researcher_agent_3],     description="Runs multiple research agents in parallel to gather information." ) # --- 3. Define the Merger Agent (Runs *after* the parallel agents) --- # This agent takes the results stored in the session state by the parallel agents # and synthesizes them into a single, structured response with attributions. merger_agent = LlmAgent(     name="SynthesisAgent",     model=GEMINI_MODEL,  # Or potentially a more powerful model if needed for synthesis     instruction="""You are an AI Assistant responsible for combining research findings into a structured report. Your primary task is to synthesize the following research summaries, clearly attributing findings to their source areas. Structure your response using headings for each topic. Ensure the report is coherent and integrates the key points smoothly. **Crucially: Your entire response MUST be grounded *exclusively* on the information provided in the 'Input Summaries' below. Do NOT add any external knowledge, facts, or details not present in these specific summaries.** **Input Summaries:** *   **Renewable Energy:**     {renewable_energy_result} *   **Electric Vehicles:**     {ev_technology_result} *   **Carbon Capture:**     {carbon_capture_result} **Output Format:** ## Summary of Recent Sustainable Technology Advancements ### Renewable Energy Findings (Based on RenewableEnergyResearcher's findings) [Synthesize and elaborate *only* on the renewable energy input summary provided above.] ### Electric Vehicle Findings (Based on EVResearcher's findings) [Synthesize and elaborate *only* on the EV input summary provided above.] ### Carbon Capture Findings (Based on CarbonCaptureResearcher's findings) [Synthesize and elaborate *only* on the carbon capture input summary provided above.] ### Overall Conclusion [Provide a brief (1-2 sentence) concluding statement that connects *only* the findings presented above.] Output *only* the structured report following this format. Do not include introductory or concluding phrases outside this structure, and strictly adhere to using only the provided input summary content. """,     description="Combines research findings from parallel agents into a structured, cited report, strictly grounded on provided inputs.",     # No tools needed for merging     # No output_key needed here, as its direct response is the final output of the sequence ) # --- 4. Create the SequentialAgent (Orchestrates the overall flow) --- # This is the main agent that will be run. It first executes the ParallelAgent # to populate the state, and then executes the MergerAgent to produce the final output. sequential_pipeline_agent = SequentialAgent(     name="ResearchAndSynthesisPipeline",     # Run parallel research first, then merge     sub_agents=[parallel_research_agent, merger_agent],     description="Coordinates parallel research and synthesizes the results." ) root_agent = sequential_pipeline_agent

这段代码定义了一个多智能体系统，用于研究和整合可持续技术发展方面的信息。它设置了三个 LlmAgent 实例作为专门的研究员。ResearcherAgent_1 专注于可再生能源，ResearcherAgent_2 研究电动汽车技术，ResearcherAgent_3 研究碳捕获方法。每个研究员智能体都配置为使用 GEMINI_MODEL 模型和 google_search 工具。它们被指示用简洁的语言（1-2 句话）总结研究结果，并使用 output_key 将这些摘要存储在会话状态中。

This code defines a multi-agent system used to research and synthesize information on sustainable technology advancements. It sets up three LlmAgent instances to act as specialized researchers. ResearcherAgent_1 focuses on renewable energy sources, ResearcherAgent_2 researches electric vehicle technology, and ResearcherAgent_3 investigates carbon capture methods. Each researcher agent is configured to use a GEMINI_MODEL and the google_search tool. They are instructed to summarize their findings concisely (1-2 sentences) and store these summaries in the session state using output_key.

然后创建一个名为 ParallelWebResearchAgent 的并行代理，用于并发运行这三个研究人员代理。这样可以并行开展研究，从而节省时间。当所有子代理（即研究人员）都完成任务并填充状态后，并行代理的执行即告结束。

A ParallelAgent named ParallelWebResearchAgent is then created to run these three researcher agents concurrently. This allows the research to be conducted in parallel, potentially saving time. The ParallelAgent completes its execution once all its sub-agents (the researchers) have finished and populated the state.

接下来，定义了一个合并代理（MergerAgent，也称 LlmAgent）来综合研究结果。该代理以并行研究人员存储在会话状态中的摘要作为输入。其指令强调输出必须严格基于提供的输入摘要，禁止添加外部知识。合并代理旨在将综合后的研究结果组织成一份报告，报告包含每个主题的标题以及一个简要的总体结论。

Next, a MergerAgent (also an LlmAgent) is defined to synthesize the research results. This agent takes the summaries stored in the session state by the parallel researchers as input. Its instruction emphasizes that the output must be strictly based only on the provided input summaries, prohibiting the addition of external knowledge. The MergerAgent is designed to structure the combined findings into a report with headings for each topic and a brief overall conclusion.

最后，创建一个名为 ResearchAndSynthesisPipeline 的 SequentialAgent 来协调整个工作流程。作为主控制器， 该主代理首先执行 ParallelAgent 进行研究。ParallelAgent 完成后，SequentialAgent 再执行 MergerAgent 来综合收集到的信息。sequential_pipeline_agent 被设置为 root_agent，代表运行此多代理系统的入口点。整个流程旨在高效地并行收集来自多个来源的信息，然后将其合并成一份结构化的报告。

Finally, a SequentialAgent named ResearchAndSynthesisPipeline is created to orchestrate the entire workflow. As the primary controller, t his main agent first executes t he ParallelAgent to perform the research. Once the ParallelAgent is complete, the SequentialAgent then executes the MergerAgent to synthesize the collected information. The sequential_pipeline_agent is set as the root_agent, representing the entry point for running this multi-agent system. The overall process is designed to efficiently gather information from multiple sources in parallel and then combine it into a single, structured report.

概览

At a Glance

问题： 许多智能体工作流包含多个子任务，这些子任务必须完成才能达成最终目标。纯粹的顺序执行（即每个任务等待前一个任务完成）通常效率低下且速度缓慢。当任务依赖于外部 I/O 操作（例如调用不同的 API 或查询多个数据库）时，这种延迟会成为严重的瓶颈。如果没有并发执行机制，总处理时间就是所有单个任务持续时间的总和，这将影响系统的整体性能和响应速度。

What: Many agentic workflows involve multiple sub-tasks that must be completed to achieve a final goal. A purely sequential execution, where each task waits for the previous one to finish, is often inefficient and slow. This latency becomes a significant bottleneck when tasks depend on external I/O operations, such as calling different APIs or querying multiple databases. Without a mechanism for concurrent execution, the total processing time is the sum of all individual task durations, hindering the system's overall performance and responsiveness.

原因： 并行化模式通过支持独立任务的并行执行，提供了一种标准化的解决方案。其工作原理是识别工作流中彼此不依赖直接输出的组件，例如工具使用或LLM调用。LangChain和Google ADK等代理框架提供了内置结构来定义和管理这些并发操作。例如，主进程可以调用多个并行运行的子任务，并在所有子任务完成后再执行下一步。通过同时运行这些独立任务而不是依次运行，这种模式可以显著减少总执行时间。

Why: The Parallelization pattern provides a standardized solution by enabling the simultaneous execution of independent tasks. It works by identifying components of a workflow, like tool usages or LLM calls, that do not rely on each other's immediate outputs. Agentic frameworks like LangChain and the Google ADK provide built-in constructs to define and manage these concurrent operations. For instance, a main process can invoke several sub-tasks that run in parallel and wait for all of them to complete before proceeding to the next step. By running these independent tasks at the same time rather than one after another, this pattern drastically reduces the total execution time.

经验法则： 当工作流包含多个可以同时运行的独立操作时，可以使用这种模式，例如从多个 API 获取数据、处理不同的数据块或生成多个内容以供后续合成。

Rule of thumb: Use this pattern when a workflow contains multiple independent operations that can run simultaneously, such as fetching data from several APIs, processing different chunks of data, or generating multiple pieces of content for later synthesis.

可视化摘要

Visual summary

图2：并行化设计模式

Fig.2: Parallelization design pattern

要点 总结

Key Takeaways

以下是主要要点：

Here are the key takeaways:

• 并行化  是一种同时执行独立任务以提高效率的模式。
• Parallelization  is a pattern for executing independent tasks concurrently to improve efficiency.
• 当任务涉及等待外部资源（例如 API 调用）时，它尤其有用。
• It is particularly useful when tasks involve waiting for external resources, such as API calls.
• 采用并发或并行架构会带来相当大的复杂性和成本，影响设计、调试和系统日志记录等关键开发阶段。
• The adoption of a concurrent or parallel architecture introduces substantial complexity and cost, impacting key development phases such as design, debugging, and system logging.
• LangChain 和 Google ADK 等框架提供了对定义和管理并行执行的内置支持。
• Frameworks like LangChain and Google ADK provide built-in support for defining and managing parallel execution.
• 在 LangChain 表达式语言 (LCEL) 中，RunnableParallel 是一个关键构造，用于并排运行多个可运行对象。
• In LangChain Expression Language (LCEL), RunnableParallel is a key construct for running multiple runnables side-by-side.
• Google ADK 可以通过LLM 驱动的委托 来促进并行执行，其中协调器代理的 LLM 识别独立的子任务，并触发专门的子代理对它们的并发处理。
• Google ADK can facilitate parallel execution through LLM-Driven Delegation , where a Coordinator agent's LLM identifies independent sub-tasks and triggers their concurrent handling by specialized sub-agents.
• 并行化有助于降低整体延迟，并使代理系统对复杂任务的响应速度更快。
• Parallelization helps reduce overall latency and makes agentic systems more responsive for complex tasks.

结论

Conclusion

并行化模式是一种通过并发执行独立的子任务来优化计算工作流程的方法。这种方法可以降低整体延迟，尤其是在涉及多个模型推理或调用外部服务的复杂操作中。

The parallelization pattern is a method for optimizing computational workflows by concurrently executing independent sub-tasks. This approach reduces overall latency, particularly in complex operations that involve multiple model inferences or calls to external services.

不同的框架提供了实现这种模式的不同机制。在 LangChain 中，像 RunnableParallel 这样的构造用于显式地定义和同时执行多个处理链。相比之下，像 Google Agent Developer Kit (ADK) 这样的框架可以通过多代理委托来实现并行化，其中主协调器模型将不同的子任务分配给可以并发运行的专用代理。

Frameworks provide distinct mechanisms for implementing this pattern. In LangChain, constructs like RunnableParallel are used to explicitly define and execute multiple processing chains simultaneously. In contrast, frameworks like the Google Agent Developer Kit (ADK) can achieve parallelization through multi-agent delegation, where a primary coordinator model assigns different sub-tasks to specialized agents that can operate concurrently.

通过将并行处理与顺序（链接）和条件（路由）控制流相结合，可以构建复杂的、高性能的计算系统，从而有效地管理各种复杂的任务。

By integrating parallel processing with sequential (chaining) and conditional (routing) control flows, it becomes possible to construct sophisticated, high-performance computational systems capable of efficiently managing diverse and complex tasks.

参考

References

以下是一些关于并行化模式及相关概念的深入阅读资源：

Here are some resources for further reading on the Parallelization pattern and related concepts:

1. LangChain表达式语言（LCEL）文档（并行性）： https://python.langchain.com/docs/concepts/lcel/  
2. LangChain Expression Language (LCEL) Documentation (Parallelism): https://python.langchain.com/docs/concepts/lcel/  
3. Google Agent Developer Kit (ADK) 文档（多代理系统）： https://google.github.io/adk-docs/agents/multi-agents/
4. Google Agent Developer Kit (ADK) Documentation (Multi-Agent Systems): https://google.github.io/adk-docs/agents/multi-agents/
5. Python asyncio 文档  ： https://docs.python.org/3/library/asyncio.html
6. Python asynci o  Documentation: https://docs.python.org/3/library/asyncio.html

第四章： 反思

Chapter 4: Reflection

反射 模式概述

Reflection Pattern Overview

在前几章中，我们探讨了基本的智能体模式：链式模式用于顺序执行，路由模式用于动态路径选择，并行化模式用于并发任务执行。这些模式使智能体能够更高效、更灵活地执行复杂任务。然而，即使拥有复杂的流程，智能体的初始输出或计划也可能并非最优、准确或完整。这时， 反射  模式就派上了用场。

In the preceding chapters, we've explored fundamental agentic patterns: Chaining for sequential execution, Routing for dynamic path selection, and Parallelization for concurrent task execution. These patterns enable agents to perform complex tasks more efficiently and flexibly. However, even with sophisticated workflows, an agent's initial output or plan might not be optimal, accurate, or complete. This is where the Reflection  pattern comes into play.

反思模式是指智能体评估自身的工作、输出或内部状态，并利用评估结果来改进自身表现或优化响应。这是一种自我纠正或自我改进的方式，使智能体能够根据反馈、内部评价或与预期标准的比较，迭代地优化输出或调整方法。 有时，反思可以由一个独立的智能体来辅助完成，该智能体的特定职责是分析初始智能体的输出。

The Reflection pattern involves an agent evaluating its own work, output, or internal state and using that evaluation to improve its performance or refine its response. It's a form of self-correction or self-improvement, allowing the agent to iteratively refine its output or adjust its approach based on feedback, internal critique, or comparison against desired criteria. Reflection can occasionally be facilitated by a separate agent whose specific role is to analyze the output of an initial agent.

与简单的顺序链（输出直接传递到下一步）或路由（选择路径）不同，反射引入了一个反馈回路。智能体不仅产生输出，还会检查该输出（或生成该输出的过程），识别潜在问题或需要改进的地方，并利用这些洞察来生成更好的版本或调整其未来的行动。

Unlike a simple sequential chain where output is passed directly to the next step, or routing which chooses a path, reflection introduces a feedback loop. The agent doesn't just produce an output; it then examines that output (or the process that generated it), identifies potential issues or areas for improvement, and uses those insights to generate a better version or modify its future actions.

该过程通常包括：

The process typically involves:

1. 执行：  代理执行任务或生成初始输出。
2. Execution:  The agent performs a task or generates an initial output.
3. 评估/评析：  代理人（通常使用另一次LLM调用或一套规则）分析上一步的结果。此评估可能检查事实准确性、连贯性、风格、完整性、是否遵守指示或其他相关标准。
4. Evaluation/Critique:  The agent (often using another LLM call or a set of rules) analyzes the result from the previous step. This evaluation might check for factual accuracy, coherence, style, completeness, adherence to instructions, or other relevant criteria.
5. 反思/改进：  根据反馈意见，智能体会如何改进。这可能包括生成更精细的输出结果、调整后续步骤的参数，甚至修改整体方案。
6. Reflection/Refinement:  Based on the critique, the agent determines how to improve. This might involve generating a refined output, adjusting parameters for a subsequent step, or even modifying the overall plan.
7. 迭代（可选但常见）：  然后可以执行改进后的输出或调整后的方法，并重复反射过程，直到获得满意的结果或满足停止条件。
8. Iteration (Optional but common):  The refined output or adjusted approach can then be executed, and the reflection process can repeat until a satisfactory result is achieved or a stopping condition is met.

反思模式的一个关键且高效的实现方式是将过程拆分为两个截然不同的逻辑角色：生产者和评论者。这通常被称为“生成者-评论者”或“生产者-评论者”模型。虽然单个代理可以进行自我反思，但使用两个专门的代理（或使用不同的系统提示进行两次独立的LLM调用）通常能产生更稳健、更客观的结果。

A key and highly effective implementation of the Reflection pattern separates the process into two distinct logical roles: a Producer and a Critic. This is often called the "Generator-Critic" or "Producer-Reviewer" model. While a single agent can perform self-reflection, using two specialized agents (or two separate LLM calls with distinct system prompts) often yields more robust and unbiased results.

1. 生产者代理：该代理的主要职责是执行任务的初始阶段。它专注于生成内容，无论是编写代码、撰写博客文章还是制定计划。它接收初始提示并生成输出的初始版本。

1. The Producer Agent: This agent's primary responsibility is to perform the initial execution of the task. It focuses entirely on generating the content, whether it's writing code, drafting a blog post, or creating a plan. It takes the initial prompt and produces the first version of the output.

2. 评估代理：该代理的唯一目的是评估生产者生成的输出。它被赋予一套不同的指令，通常还被赋予一个独特的角色（例如，“您是一位资深软件工程师”、“您是一位一丝不苟的事实核查员”）。评估代理的指令指导它根据特定标准分析生产者的工作，例如事实准确性、代码质量、风格要求或完整性。它的设计目的是发现缺陷、提出改进建议并提供结构化的反馈。

2. The Critic Agent: This agent's sole purpose is to evaluate the output generated by the Producer. It is given a different set of instructions, often a distinct persona (e.g., "You are a senior software engineer," "You are a meticulous fact-checker"). The Critic's instructions guide it to analyze the Producer's work against specific criteria, such as factual accuracy, code quality, stylistic requirements, or completeness. It is designed to find flaws, suggest improvements, and provide structured feedback.

这种职责分离机制非常有效，因为它避免了智能体在审查自身作品时产生的“认知偏差”。评论智能体以全新的视角审视输出结果，专注于发现错误和改进之处。评论智能体的反馈随后会传递给生产智能体，生产智能体以此为指导，生成一个更加完善的新版本。提供的 LangChain 和 ADK 代码示例都实现了这种双智能体模型：LangChain 示例使用特定的“reflector_prompt”来创建评论智能体角色，而 ADK 示例则明确定义了生产智能体和评论智能体。

This separation of concerns is powerful because it prevents the "cognitive bias" of an agent reviewing its own work. The Critic agent approaches the output with a fresh perspective, dedicated entirely to finding errors and areas for improvement. The feedback from the Critic is then passed back to the Producer agent, which uses it as a guide to generate a new, refined version of the output. The provided LangChain and ADK code examples both implement this two-agent model: the LangChain example uses a specific "reflector_prompt" to create a critic persona, while the ADK example explicitly defines a producer and a reviewer agent.

实现反射通常需要构建代理的工作流程，使其包含这些反馈循环。这可以通过代码中的迭代循环来实现，或者使用支持状态管理和基于评估结果的条件转换的框架。虽然可以在 LangChain/Lang Graph、ADK 或 Crew.AI链中实现单步评估和改进  ，但真正的迭代反射通常涉及更复杂的编排。

Implementing reflection often requires structuring the agent's workflow to include these feedback loops. This can be achieved through iterative loops in code, or using frameworks that support state management and conditional transitions based on evaluation results. While a single step of evaluation and refinement can be implemented within either a LangChain/Lang Graph, or ADK, or Crew.AI  chain, true iterative reflection typically involves more complex orchestration.

反思模式对于构建能够产出高质量输出、处理复杂任务并展现一定程度的自我意识和适应能力的智能体至关重要。它使智能体不再仅仅执行指令，而是转向更复杂的解决问题和内容生成方式。

The Reflection pattern is crucial for building agents that can produce high-quality outputs, handle nuanced tasks, and exhibit a degree of self-awareness and adaptability. It moves agents beyond simply executing instructions towards a more sophisticated form of problem-solving and content generation.

反思与目标设定和监控（见第十一章）的交集值得关注。目标为智能体的自我评估提供了最终基准，而监控则跟踪其进展。在许多实际案例中，反思可以作为纠正机制，利用监控反馈来分析偏差并调整策略。这种协同作用使智能体从被动的执行者转变为一个有目的的系统，能够自适应地实现其目标。

The intersection of reflection with goal setting and monitoring (see Chapter 11) is worth noticing. A goal provides the ultimate benchmark for the agent's self-evaluation, while monitoring tracks its progress. In a number of practical cases, Reflection then might act as the corrective engine, using monitored feedback to analyze deviations and adjust its strategy. This synergy transforms the agent from a passive executor into a purposeful system that adaptively works to achieve its objectives.

此外，当逻辑逻辑模型（LLM）保留对话记忆时 （参见第 8章），反思模式的有效性将显著提升。这种对话历史记录为评估阶段提供了至关重要的上下文，使智能体不仅能够孤立地评估其输出，还能将其置于先前的交互、用户反馈和不断变化的目标背景下进行评估。这使得智能体能够从过去的批评中学习，避免重蹈覆辙。如果没有记忆，每次反思都是一个独立的事件；有了记忆，反思就变成了一个累积过程，每个循环都建立在前一个循环的基础上，从而实现更智能、更具上下文感知能力的改进。

Furthermore, the effectiveness of the Reflection pattern is significantly enhanced when the LLM keeps a memory of the conversation (see Chapter 8). This conversational history provides crucial context for the evaluation phase, allowing the agent to assess its output not just in isolation, but against the backdrop of previous interactions, user feedback, and evolving goals. It enables the agent to learn from past critiques and avoid repeating errors. Without memory, each reflection is a self-contained event; with memory, reflection becomes a cumulative process where each cycle builds upon the last, leading to more intelligent and context-aware refinement.

实际应用及案例

Practical Applications & Use Cases

在输出质量、准确性或对复杂约束的遵守至关重要的场景中，反射模式非常有用：

The Reflection pattern is valuable in scenarios where output quality, accuracy, or adherence to complex constraints is critical:

1. 创意写作和内容创作：

1. Creative Writing and Content Generation:

对生成的文本、故事、诗歌或营销文案进行润色。

Refining generated text, stories, poems, or marketing copy.

• 使用场景：  代理正在撰写博客文章。
• Use Case:  An agent writing a blog post.

• 反思：  先写出草稿，然后根据流畅性、语气和清晰度进行点评，最后根据点评修改。重复此过程，直到文章达到质量标准。
• Reflection:  Generate a draft, critique it for flow, tone, and clarity, then rewrite based on the critique. Repeat until the post meets quality standards.
• 好处：  产出更精良、更有效的内容。
• Benefit:  Produces more polished and effective content.

2. 代码生成和调试：

2. Code Generation and Debugging:

编写代码、发现错误并修复错误。

Writing code, identifying errors, and fixing them.

• 使用场景：  代理编写Python函数。
• Use Case:  An agent writing a Python function.

• 反思：  编写初始代码，运行测试或静态分析，找出错误或低效之处，然后根据发现修改代码。
• Reflection:  Write initial code, run tests or static analysis, identify errors or inefficiencies, then modify the code based on the findings.
• 优点：  生成更健壮、更高效的代码。
• Benefit:  Generates more robust and functional code.

3. 复杂问题解决：

3. Complex Problem Solving:

评估多步骤推理任务中的中间步骤或提出的解决方案。

Evaluating intermediate steps or proposed solutions in multi-step reasoning tasks.

• 使用场景：  智能体解决逻辑谜题。
• Use Case:  An agent solving a logic puzzle.

• 反思：  提出一个步骤，评估它是否更接近解决方案或引入矛盾，如果需要，回溯或选择不同的步骤。
• Reflection:  Propose a step, evaluate if it leads closer to the solution or introduces contradictions, backtrack or choose a different step if needed.
• 益处：  提高智能体处理复杂问题的能力。
• Benefit:  Improves the agent's ability to navigate complex problem spaces.

4. 总结和信息综合：

4. Summarization and Information Synthesis:

完善摘要，使其准确、完整、简洁。

Refining summaries for accuracy, completeness, and conciseness.

• 使用场景：  代理程序对长文档进行摘要。
• Use Case:  An agent summarizing a long document.

• 反思：  生成一个初步摘要，将其与原始文档中的关键点进行比较，完善摘要以包含缺失的信息或提高准确性。
• Reflection:  Generate an initial summary, compare it against key points in the original document, refine the summary to include missing information or improve accuracy.
• 优点：  生成更准确、更全面的摘要。
• Benefit:  Creates more accurate and comprehensive summaries.

5. 规划与战略：

5. Planning and Strategy:

评估拟议方案并找出潜在缺陷或改进之处。

Evaluating a proposed plan and identifying potential flaws or improvements.

• 使用案例：  智能体规划一系列行动以实现目标。
• Use Case:  An agent planning a series of actions to achieve a goal.

• 反思：  制定计划，模拟执行或评估其在约束条件下的可行性，并根据评估结果修改计划。
• Reflection:  Generate a plan, simulate its execution or evaluate its feasibility against constraints, revise the plan based on the evaluation.
• 益处：  制定更有效、更切合实际的计划。
• Benefit:  Develops more effective and realistic plans.

6. 对话式代理：

6. Conversational Agents:

回顾对话中的前几轮发言，以保持语境清晰、纠正误解或提高回答质量。

Reviewing previous turns in a conversation to maintain context, correct misunderstandings, or improve response quality.

• 使用案例：  客户支持聊天机器人。
• Use Case:  A customer support chatbot.

• 反思：  在用户回复后，查看对话历史记录和最后生成的消息，以确保连贯性并准确回应用户的最新输入。
• Reflection:  After a user response, review the conversation history and the last generated message to ensure coherence and address the user's latest input accurately.
• 好处：  有助于进行更自然、更有效的对话。
• Benefit:  Leads to more natural and effective conversations.

反思为智能体系统增加了一层元认知能力，使它们能够从自身的输出和过程中学习，从而产生更智能、更可靠、更高质量的结果。

Reflection adds a layer of meta-cognition to agentic systems, enabling them to learn from their own outputs and processes, leading to more intelligent, reliable, and high-quality results.

动手实践代码示例（LangChain）

Hands-On Code Example (LangChain)

实现完整的迭代反射过程需要状态管理和循环执行机制。虽然基于图的框架（例如 LangGraph）或自定义过程代码可以原生处理这些机制，但使用 LCEL （LangChain 表达式语言）的组合语法可以有效地演示单个反射循环的基本原理。 

The implementation of a complete, iterative reflection process necessitates mechanisms for state management and cyclical execution. While these are handled natively in graph-based frameworks like LangGraph or through custom procedural code, the fundamental principle of a single reflection cycle can be demonstrated effectively using the compositional syntax of LCEL   (LangChain Expression Language).

本 示例 使用 Langchain 库和 OpenAI 的 GPT-4o 模型实现了一个反射循环，用于迭代生成和优化一个计算数字阶乘的 Python 函数。该过程从任务提示开始，生成初始代码，然后根据模拟的高级软件工程师角色提供的反馈反复对代码进行反思，并在每次迭代中不断优化代码，直到反馈阶段认为代码已完美或达到最大迭代次数。最后，程序会打印出最终优化后的代码。

This example implements a reflection loop using the Langchain library and OpenAI's GPT-4o model to iteratively generate and refine a Python function that calculates the factorial of a number. The process starts with a task prompt, generates initial code, and then repeatedly reflects on the code based on critiques from a simulated senior software engineer role, refining the code in each iteration until the critique stage determines the code is perfect or a maximum number of iterations is reached. Finally, it prints the resulting refined code.

首先，请确保已安装必要的库：

First, ensure you have the necessary libraries installed:

pip install langchain langchain-community langchain-openai

您还需要使用您选择的语言模型（例如 OpenAI、Google Gemini、Anthropic）的 API 密钥来设置您的环境。

You will also need to set up your environment with your API key for the language model you choose (e.g., OpenAI, Google Gemini, Anthropic).

import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.messages import SystemMessage, HumanMessage # --- Configuration --- # Load environment variables from .env file (for OPENAI_API_KEY) load_dotenv() # Check if the API key is set if not os.getenv("OPENAI_API_KEY"):    raise ValueError("OPENAI_API_KEY not found in .env file. Please add it.") # Initialize the Chat LLM. We use gpt-4o for better reasoning. # A lower temperature is used for more deterministic outputs. llm = ChatOpenAI(model="gpt-4o", temperature=0.1) def run_reflection_loop():    """    Demonstrates a multi-step AI reflection loop to progressively improve a Python function.    """    # --- The Core Task ---    task_prompt = """    Your task is to create a Python function named `calculate_factorial`.    This function should do the following:    1.  Accept a single integer `n` as input.    2.  Calculate its factorial (n!).    3.  Include a clear docstring explaining what the function does.    4.  Handle edge cases: The factorial of 0 is 1.    5.  Handle invalid input: Raise a ValueError if the input is a negative number.    """    # --- The Reflection Loop ---    max_iterations = 3    current_code = ""    # We will build a conversation history to provide context in each step.    message_history = [HumanMessage(content=task_prompt)]    for i in range(max_iterations):        print("\n" + "="*25 + f" REFLECTION LOOP: ITERATION {i + 1} " + "="*25)        # --- 1. GENERATE / REFINE STAGE ---        # In the first iteration, it generates. In subsequent iterations, it refines.        if i == 0:            print("\n>>> STAGE 1: GENERATING initial code...")            # The first message is just the task prompt.            response = llm.invoke(message_history)            current_code = response.content        else:            print("\n>>> STAGE 1: REFINING code based on previous critique...")            # The message history now contains the task,            # the last code, and the last critique.            # We instruct the model to apply the critiques.            message_history.append(HumanMessage(content="Please refine the code using the critiques provided."))            response = llm.invoke(message_history)            current_code = response.content        print("\n--- Generated Code (v" + str(i + 1) + ") ---\n" + current_code)        message_history.append(response) # Add the generated code to history        # --- 2. REFLECT STAGE ---        print("\n>>> STAGE 2: REFLECTING on the generated code...")        # Create a specific prompt for the reflector agent.        # This asks the model to act as a senior code reviewer.        reflector_prompt = [            SystemMessage(content="""                You are a senior software engineer and an expert                in Python.                Your role is to perform a meticulous code review.                Critically evaluate the provided Python code based                on the original task requirements.                Look for bugs, style issues, missing edge cases,                and areas for improvement.                If the code is perfect and meets all requirements,                respond with the single phrase 'CODE_IS_PERFECT'.                Otherwise, provide a bulleted list of your critiques.            """),            HumanMessage(content=f"Original Task:\n{task_prompt}\n\nCode to Review:\n{current_code}")        ]        critique_response = llm.invoke(reflector_prompt)        critique = critique_response.content        # --- 3. STOPPING CONDITION ---        if "CODE_IS_PERFECT" in critique:            print("\n--- Critique ---\nNo further critiques found. The code is satisfactory.")            break        print("\n--- Critique ---\n" + critique)        # Add the critique to the history for the next refinement loop.        message_history.append(HumanMessage(content=f"Critique of the previous code:\n{critique}"))    print("\n" + "="*30 + " FINAL RESULT " + "="*30)    print("\nFinal refined code after the reflection process:\n")    print(current_code) if __name__ == "__main__":    run_reflection_loop()

代码首先设置环境，加载 API 密钥，并初始化一个功能强大的语言模型（例如 GPT-4o），该模型采用较低的温度设置以获得更精准的输出。核心任务由一个提示定义，该提示要求编写一个 Python 函数来计算一个数的阶乘，并包含对文档字符串、边界情况（例如 0 的阶乘）以及负数输入错误处理的具体要求。`run_reflection_loop` 函数  负责协调迭代优化过程。在循环中，第一次迭代时，语言模型根据任务提示生成初始代码。在后续迭代中，它会根据上一步的反馈对代码进行优化。另一个由语言模型扮演的“反射器”角色（但使用不同的系统提示）则扮演高级软件工程师的角色，根据原始任务要求对生成的代码进行评估。评估结果以问题列表的形式呈现，如果没有发现任何问题，则会显示“代码完美”。循环持续进行，直到评估结果表明代码完美，或者达到最大迭代次数为止。对话历史记录会被维护，并在每个步骤中传递给语言模型，以便为生成/细化和反思阶段提供上下文。最后，脚本会在循环结束后打印最后生成的代码版本。

The code  begins by setting up the environment, loading API keys, and initializing a powerful language model like GPT-4o with a low temperature for focused outputs. The core task is defined by a prompt asking for a Python function to calculate the factorial of a number, including specific requirements for docstrings, edge cases (factorial of 0), and error handling for negative input. The run_reflection_loop  function orchestrates the iterative refinement process. Within the loop, in the first iteration, the language model generates initial code based on the task prompt. In subsequent iterations, it refines the code based on critiques from the previous step. A separate "reflector" role, also played by the language model but with a different system prompt, acts as a senior software engineer to critique the generated code against the original task requirements. This critique is provided as a bulleted list of issues or the phrase 'CODE_IS_PERFECT' if no issues are found. The loop continues until the critique indicates the code is perfect or a maximum number of iterations is reached. The conversation history is maintained and passed to the language model in each step to provide context for both generation/refinement and reflection stages. Finally, the script prints the last generated code version after the loop concludes.

动手实践代码示例（ADK）

Hands-On Code Example (ADK)

现在我们来看一个使用 Google ADK 实现的概念性代码示例。具体来说，该代码通过采用  生成器-评论家结构来展示这一点， 其中一个组件（生成器）生成初始结果或计划，而另一个组件（评论家）提供关键反馈或评论，引导生成器生成更完善或更准确的最终输出。

Let's now look at a conceptual code example implemented using the Google ADK.  Specifically, the code showcases this by employing  a Generator-Critic structure, w here one component (the Generator) produces an initial result or plan, and another component (the Critic) provides critical feedback or a critique, guiding the Generator towards a more refined or accurate final output.

from google.adk.agents import SequentialAgent, LlmAgent # The first agent generates the initial draft. generator = LlmAgent(    name="DraftWriter",    description="Generates initial draft content on a given subject.",    instruction="Write a short, informative paragraph about the user's subject.",    output_key="draft_text" # The output is saved to this state key. ) # The second agent critiques the draft from the first agent. reviewer = LlmAgent(    name="FactChecker",    description="Reviews a given text for factual accuracy and provides a structured critique.",    instruction="""    You are a meticulous fact-checker.    1. Read the text provided in the state key 'draft_text'.    2. Carefully verify the factual accuracy of all claims.    3. Your final output must be a dictionary containing two keys:       - "status": A string, either "ACCURATE" or "INACCURATE".       - "reasoning": A string providing a clear explanation for your status, citing specific issues if any are found.    """,    output_key="review_output" # The structured dictionary is saved here. ) # The SequentialAgent ensures the generator runs before the reviewer. review_pipeline = SequentialAgent(    name="WriteAndReview_Pipeline",    sub_agents=[generator, reviewer] ) # Execution Flow: # 1. generator runs -> saves its paragraph to state['draft_text']. # 2. reviewer runs -> reads state['draft_text'] and saves its dictionary output to state['review_output'].

这段代码演示了如何在 Google ADK 中使用顺序代理管道来生成和审核文本。它定义了两个 LlmAgent 实例：生成器和审核器。生成器代理用于生成给定主题的初始草稿段落。它被指示生成一段简短且信息丰富的文本，并将输出保存到状态键 draft_text 中。审核器代理充当生成器生成的文本的事实核查器。它被指示从 draft_text 读取文本并验证其事实准确性。审核器的输出是一个结构化字典，包含两个键：status 和 reasoning。status 指示文本是“准确”还是“不准确”，而 reasoning 则提供对状态的解释。该字典保存到状态键 review_output 中。创建了一个名为 review_pipeline 的 SequentialAgent 来管理这两个代理的执行顺序。它确保生成器先运行，然后是审核器。整个执行流程是：生成器生成文本，然后将其保存到状态中。随后，审核员从状态中读取文本，进行事实核查，并将结果（状态和理由）保存回状态。此流程允许使用独立的代理进行结构化的内容创建和审核。 注：  感兴趣的用户还可以使用基于 ADK LoopAgent 的替代实现方案。

This code demonstrates the use of a sequential agent pipeline in Google ADK  for generating and reviewing text. It defines two LlmAgent instances: generator and reviewer. The generator agent is designed to create an initial draft paragraph on a given subject. It is instructed to write a short and informative piece and saves its output to the state key draft_text. The reviewer agent acts as a fact-checker for the text produced by the generator. It is instructed to read the text from draft_text and verify its factual accuracy. The reviewer's output is a structured dictionary with two keys: status and reasoning. status indicates if the text is "ACCURATE" or "INACCURATE", while reasoning provides an explanation for the status. This dictionary is saved to the state key review_output. A SequentialAgent named review_pipeline is created to manage the execution order of the two agents. It ensures that the generator runs first, followed by the reviewer. The overall execution flow is that the generator produces text, which is then saved to the state. Subsequently, the reviewer reads this text from the state, performs its fact-checking, and saves its findings (the status and reasoning) back to the state. This pipeline allows for a structured process of content creation and review using separate agents. Note:  An alternative implementation utilizing ADK's LoopAgent is also available for those interested.

在得出结论之前，需要注意的是，虽然反射模式能够显著提升输出质量，但它也存在一些重要的权衡取舍。迭代过程虽然强大，但会导致更高的成本和延迟，因为每次迭代循环都可能需要调用新的 LLM 函数，这使得它对于时间敏感型应用来说并非最佳选择。此外，该模式非常消耗内存；每次迭代都会扩展对话历史记录，包括初始输出、评论和后续的改进。

Before concluding, it's important to consider that while the Reflection pattern significantly enhances output quality, it comes with important trade-offs. The iterative process, though powerful, can lead to higher costs and latency, since every refinement loop may require a new LLM call, making it suboptimal for time-sensitive applications. Furthermore, the pattern is memory-intensive; with each iteration, the conversational history expands, including the initial output, critique, and subsequent refinements.

概览

At Glance

问题：  智能体的初始输出通常并非最优，可能存在不准确、不完整或无法满足复杂需求等问题。基本的智能体工作流程缺乏内置机制来识别和修复自身错误。解决之道在于让智能体评估自身的工作，或者更稳健地，引入一个独立的逻辑智能体作为评判者，从而避免不顾质量而将初始响应直接作为最终结果。

What:  An agent's initial output is often suboptimal, suffering from inaccuracies, incompleteness, or a failure to meet complex requirements. Basic agentic workflows lack a built-in process for the agent to recognize and fix its own errors. This is solved by having the agent evaluate its own work or, more robustly, by introducing a separate logical agent to act as a critic, preventing the initial response from being the final one regardless of quality.

原因：  反射模式通过引入自我纠错和改进机制提供了一种解决方案。它建立了一个反馈回路，其中“生产者”代理生成输出，然后“评论者”代理（或生产者自身）根据预定义的标准对其进行评估。该评论随后用于生成改进版本。这种生成、评估和改进的迭代过程逐步提高最终结果的质量，从而获得更准确、更连贯、更可靠的结果。

Why:  The Reflection pattern offers a solution by introducing a mechanism for self-correction and refinement. It establishes a feedback loop where a "producer" agent generates an output, and then a "critic" agent (or the producer itself) evaluates it against predefined criteria. This critique is then used to generate an improved version. This iterative process of generation, evaluation, and refinement progressively enhances the quality of the final result, leading to more accurate, coherent, and reliable outcomes.

经验法则：  当最终输出的质量、准确性和细节比速度和成本更重要时，应使用反射模式。它尤其适用于生成精炼的长篇内容、编写和调试代码以及​​创建详细计划等任务。当任务需要高度客观性或专业评估，而通用型生产者代理可能忽略这些方面时，则应使用单独的评论代理。

Rule of thumb:  Use the Reflection pattern when the quality, accuracy, and detail of the final output are more important than speed and cost. It is particularly effective for tasks like generating polished long-form content, writing and debugging code, and creating detailed plans. Employ a separate critic agent when tasks require high objectivity or specialized evaluation that a generalist producer agent might miss.

可视化摘要

Visual summary

图1：反射设计图案，自反射

Fig. 1: Reflection design pattern, self-reflection

图2：反思设计模式、生产者和评论者

Fig.2: Reflection design pattern, producer and critique agent

要点 总结

Key Takeaways

• 反射模式的主要优势在于它能够迭代地自我纠正和改进输出，从而显著提高质量、准确性和对复杂指令的遵守程度。
• The primary advantage of the Reflection pattern is its ability to iteratively self-correct and refine outputs, leading to significantly higher quality, accuracy, and adherence to complex instructions.
• 它包含执行、评估/评论和改进的反馈循环。对于需要高质量、准确或细致输出的任务而言，反思至关重要。
• It involves a feedback loop of execution, evaluation/critique, and refinement. Reflection is essential for tasks requiring high-quality, accurate, or nuanced outputs.
• 生产者-评论家模型是一种强有力的实现方式，其中由一个独立的主体（或被引导的角色）来评估初始输出。这种职责分离增强了客观性，并允许提供更专业、更结构化的反馈。
• A powerful implementation is the Producer-Critic model, where a separate agent (or prompted role) evaluates the initial output. This separation of concerns enhances objectivity and allows for more specialized, structured feedback.
• 然而，这些好处是以增加延迟和计算成本为代价的，同时还存在超出模型上下文窗口或被 API 服务限制的风险。
• However, these benefits come at the cost of increased latency and computational expense, along with a higher risk of exceeding the model's context window or being throttled by API services.
• 虽然完整的迭代反思通常需要有状态的工作流（如 LangGraph），但可以使用 LCEL 在 LangChain 中实现单个反思步骤，以传递输出进行评判和后续改进。
• While full iterative reflection often requires stateful workflows (like LangGraph), a single reflection step can be implemented in LangChain using LCEL to pass output for critique and subsequent refinement.
• Google ADK 可以通过顺序工作流程促进反思，其中一个代理的输出由另一个代理进行评判，从而允许后续的改进步骤。
• Google ADK can facilitate reflection through sequential workflows where one agent's output is critiqued by another agent, allowing for subsequent refinement steps.
• 这种模式使智能体能够进行自我纠正，并随着时间的推移提高其性能。
• This pattern enables agents to perform self-correction and enhance their performance over time.

结论

Conclusion

反射模式为智能体工作流程中的自我纠错提供了一种关键机制，使其能够超越单次执行进行迭代改进。其实现方式是创建一个循环：系统生成输出，根据特定标准对其进行评估，然后利用该评估结果生成更优的结果。这种评估可以由智能体自身执行（自我反射），或者通常更有效的方式是由独立的评估智能体执行，这体现了该模式的一个关键架构选择。

The reflection pattern provides a crucial mechanism for self-correction within an agent's workflow, enabling iterative improvement beyond a single-pass execution. This is achieved by creating a loop where the system generates an output, evaluates it against specific criteria, and then uses that evaluation to produce a refined result. This evaluation can be performed by the agent itself (self-reflection) or, often more effectively, by a distinct critic agent, which represents a key architectural choice within the pattern.

虽然完全自主的多步骤反思过程需要强大的状态管理架构，但其核心原则可以通过单一的生成-批判-改进循环有效地展现出来。作为一种控制结构，反思可以与其他基础模式相结合，构建更强大、功能更复杂的智能体系统。

While a fully autonomous, multi-step reflection process requires a robust architecture for state management, its core principle is effectively demonstrated in a single generate-critique-refine cycle. As a control structure, reflection can be integrated with other foundational patterns to construct more robust and functionally complex agentic systems.

参考

References

以下是一些关于反射模式及相关概念的深入阅读资源：

Here are some resources for further reading on the Reflection pattern and related concepts:

1. 通过强化学习训练语言模型实现自我纠错， https://arxiv.org/abs/2409.12917  
2. Training Language Models to Self-Correct via Reinforcement Learning, https://arxiv.org/abs/2409.12917  
3. LangChain表达式语言（LCEL）文档： https://python.langchain.com/docs/introduction/  
4. LangChain Expression Language (LCEL) Documentation: https://python.langchain.com/docs/introduction/  
5. LangGraph 文档： https://www.langchain.com/langgraph  
6. LangGraph Documentation: https://www.langchain.com/langgraph  
7. Google Agent Developer Kit (ADK) 文档（多代理系统）： https://google.github.io/adk-docs/agents/multi-agents/
8. Google Agent Developer Kit (ADK) Documentation (Multi-Agent Systems): https://google.github.io/adk-docs/agents/multi-agents/

第五章：工具使用（函数调用）

Chapter 5: Tool Use (Function Calling)

工具使用模式概述

Tool Use Pattern Overview

到目前为止，我们讨论的代理模式主要涉及协调语言模型之间的交互以及管理代理内部工作流程中的信息流（链式调用、路由、并行化、反射）。然而，为了使代理真正有用并与现实世界或外部系统交互，它们需要具备 使用 工具的能力 。

So far, we've discussed agentic patterns that primarily involve orchestrating interactions between language models and managing the flow of information within the agent's internal workflow (Chaining, Routing, Parallelization, Reflection). However, for agents to be truly useful and interact with the real world or external systems, they need the ability t o use Tools .

工具使用模式（通常通过称为函数调用的机制实现 ） 使 代理能够与外部 API、 数据库、服务进行交互，甚至执行代码。它允许代理核心的 LLM 根据用户的请求或任务的当前状态来决定何时以及如何使用特定的外部函数。

The Tool Use pattern, often implemented through a mechanism calle d Function Calling , enables an agent to interact with external APIs, data bases, services, or even execute code. It allows the LLM at the core of the agent to decide when and how to use a specific external function based on the user's request or the current state of the task.

该过程通常包括：

The process typically involves:

1. 工具定义：  外部功能或特性需向LLM进行定义和描述。此描述包括功能的用途、名称、接受的参数及其类型和描述。
2. Tool Definition:  External functions or capabilities are defined and described to the LLM. This description includes the function's purpose, its name, and the parameters it accepts, along with their types and descriptions.
3. LLM决策：  LLM接收用户请求和可用工具定义。基于对请求和工具的理解，LLM决定是否需要调用一个或多个工具来满足请求。
4. LLM Decision:  The LLM receives the user's request and the available tool definitions. Based on its understanding of the request and the tools, the LLM decides if calling one or more tools is necessary to fulfill the request.
5. 函数调用生成：  如果 LLM 决定使用某个工具，它会生成一个结构化的输出（通常是一个 JSON 对象），其中指定了要调用的工具的名称以及要传递给它的参数，这些参数是从用户的请求中提取出来的。
6. Function Call Generation:  If the LLM decides to use a tool, it generates a structured output (often a JSON object) that specifies the name of the tool to call and the arguments (parameters) to pass to it, extracted from the user's request.
7. 工具执行：  代理框架或编排层拦截此结构化输出。它识别请求的工具，并使用提供的参数执行实际的外部函数。
8. Tool Execution:  The agentic framework or orchestration layer intercepts this structured output. It identifies the requested tool and executes the actual external function with the provided arguments.
9. 观察/结果：  工具执行的输出或结果将返回给代理。
10. Observation/Result:  The output or result from the tool execution is returned to the agent.
11. LLM 处理（可选但常见）：  LLM 接收工具的输出作为上下文，并用它来形成对用户的最终响应，或决定工作流程中的下一步（这可能涉及调用另一个工具、反思或提供最终答案）。
12. LLM Processing (Optional but common):  The LLM receives the tool's output as context and uses it to formulate a final response to the user or decide on the next step in the workflow (which might involve calling another tool, reflecting, or providing a final answer).

这种模式至关重要，因为它突破了LLM训练数据的限制，使其能够访问最新信息、执行内部无法完成的计算、与用户特定数据交互或触发现实世界的操作。函数调用是弥合LLM推理能力与各种可用外部功能之间差距的技术机制。

This pattern is fundamental because it breaks the limitations of the LLM's training data and allows it to access up-to-date information, perform calculations it can't do internally, interact with user-specific data, or trigger real-world actions. Function calling is the technical mechanism that bridges the gap between the LLM's reasoning capabilities and the vast array of external functionalities available.

“函数调用”虽然恰当地描述了调用特定的、预定义的代码函数，但考虑“工具调用”这个更广泛的概念也很有意义。这个更宽泛的术语承认，代理的功能远不止于简单的函数执行。“工具”可以是传统的函数，也可以是复杂的API接口、数据库请求，甚至是指向另一个专用代理的指令。这种视角使我们能够设想更复杂的系统，例如，主代理可以将复杂的数据分析任务委托给专门的“分析代理”，或者通过其API查询外部知识库。从“工具调用”的角度思考，能更好地体现代理在由数字资源和其他智能实体组成的多样化生态系统中作为协调者的全部潜力。

While "function calling" aptly describes invoking specific, predefined code functions, it's useful to consider the more expansive concept of "tool calling." This broader term acknowledges that an agent's capabilities can extend far beyond simple function execution. A "tool" can be a traditional function, but it can also be a complex API endpoint, a request to a database, or even an instruction directed at another specialized agent. This perspective allows us to envision more sophisticated systems where, for instance, a primary agent might delegate a complex data analysis task to a dedicated "analyst agent" or query an external knowledge base through its API. Thinking in terms of "tool calling" better captures the full potential of agents to act as orchestrators across a diverse ecosystem of digital resources and other intelligent entities.

LangChain、LangGraph 和 Google Agent Developer Kit (ADK) 等框架为定义工具并将其集成到代理工作流程中提供了强大的支持，通常会利用 Gemini 或 OpenAI 系列等现代语言学习模型 (LLM) 的原生函数调用功能。在这些框架的“画布”上，您可以定义工具，然后配置代理（通常是 语言 学习模型 代理 ）以使其能够感知并使用这些工具。

Frameworks like LangChain, LangGraph, and Google Agent Developer Kit (ADK) provide robust support for defining tools and integrating them into agent workflows, often leveraging the native function calling capabilities of modern LLMs like those in the Gemini or OpenAI series. On the "canvas" of these frameworks, you define the tools and then configure agents (typically L LM Agents ) to be aware of and capable of using these tools.

工具使用是构建功能强大、交互式且具有外部感知能力的代理的基石模式。

Tool Use is a cornerstone pattern for building powerful, interactive, and externally aware agents.

实际应用及案例

Practical Applications & Use Cases

工具使用模式几乎适用于任何需要代理超越生成文本来执行操作或检索特定动态信息的场景：

The Tool Use pattern is applicable in virtually any scenario where an agent needs to go beyond generating text to perform an action or retrieve specific, dynamic information:

1. 从外部来源检索信息：

1. Information Retrieval from External Sources:

获取LLM训练数据中不存在的实时数据或信息。

Accessing real-time data or information that is not present in the LLM's training data.

• 应用案例：  天气预报代理。
• Use Case:  A weather agent.

• 工具：  一个天气 API，接受位置信息并返回当前天气状况。
• Tool:  A weather API that takes a location and returns the current weather conditions.
• 代理流程：  用户询问“伦敦天气如何？”，LLM 识别出对天气工具的需求，调用该工具并输入“伦敦”，工具返回数据，LLM 将数据格式化为用户友好的响应。
• Agent Flow:  User asks, "What's the weather in London?", LLM identifies the need for the weather tool, calls the tool with "London", tool returns data, LLM formats the data into a user-friendly response.

2. 与数据库和 API 交互：

2. Interacting with Databases and APIs:

对结构化数据执行查询、更新或其他操作。

Performing queries, updates, or other operations on structured data.

• 使用案例：  电子商务代理。
• Use Case:  An e-commerce agent.

• 工具：  通过 API 调用来检查产品库存、获取订单状态或处理付款。
• Tools:  API calls to check product inventory, get order status, or process payments.
• 代理流程：  用户询问“产品 X 是否有库存？”， LLM  调用 库存 API，工具返回库存数量，LLM 告诉用户库存状态。
• Agent Flow:  User asks "Is product X in stock?", LLM  calls the inventory API, tool returns stock count, LLM tells the user the stock status.

3. 进行计算和数据分析：

3. Performing Calculations and Data Analysis:

使用外部计算器、数据分析库或统计工具。

Using external calculators, data analysis libraries, or statistical tools.

• 使用案例：  金融代理人。
• Use Case:  A financial agent.

• 工具：  计算器功能、股票市场数据 API、电子表格工具。
• Tools:  A calculator function, a stock market data API, a spreadsheet tool.
• 代理流程：  用户询问“苹果公司 (AAPL) 的当前价格是多少？如果我以每股 150 美元的价格购买 100 股，潜在利润是多少？”，LLM 调用股票 API，获取当前价格，然后调用计算器工具，获取结果，格式化响应。
• Agent Flow:  User asks "What's the current price of AAPL and calculate the potential profit if I bought 100 shares at $150?", LLM calls stock API, gets current price, then calls calculator tool, gets result, formats response.

4. 发送信息：

4. Sending Communications:

向外部通信服务发送电子邮件、消息或发出 API 调用。

Sending emails, messages, or making API calls to external communication services.

• 使用案例：  个人助理代理。
• Use Case:  A personal assistant agent.

• 工具：  邮件发送API。
• Tool:  An email sending API.
• 代理流程：  用户说 ，  “给约翰发一封关于明天会议的电子邮件 。 ”，LLM 调用电子邮件  工具，并 从请求中提取收件人、主题和正文。
• Agent Flow:  User says ,  "Send an email to John about the meeting tomorrow . ", LLM calls an email  tool with the recipient, subject, and body extracted from the request.

5. 执行代码：

5. Executing Code:

在安全的环境中运行代码片段以执行特定任务。

Running code snippets in a safe environment to perform specific tasks.

• 使用案例：  编码辅助代理。
• Use Case:  A coding assistant agent.

• 工具：  代码解释器。
• Tool:  A code interpreter.
• 代理流程：  用户提供一段 Python 代码片段并询问 “  这段代码的作用是什么？”，LLM 使用解释器工具运行代码并分析其输出。
• Agent Flow:  User provides a Python snippet and asks ,  "What does this code do?", LLM uses the interpreter tool to run the code and analyze its output.

6. 控制其他系统或设备：

6. Controlling Other Systems or Devices:

与智能家居设备、物联网平台或其他联网系统进行交互。

Interacting with smart home devices, IoT platforms, or other connected systems.

• 应用案例：  智能家居代理。
• Use Case:  A smart home agent.

• 工具：  用于控制智能灯的API。
• Tool:  An API to control smart lights.
• 代理流程：  用户说 ：  “关掉客厅的灯 。 ” LLM 使用该命令和目标设备调用智能家居工具。
• Agent Flow:  User says ,  "Turn off the living room lights . " LLM calls the smart home tool with the command and target device.

工具的使用将语言模型从文本生成器转变为能够在数字或物理世界 中感知、推理和行动的代理 （见图 1）。

Tool Use is what transforms a language model from a text generator into an agent capable of sensing, reasoning, and acting in the digital or physical world  (see Fig. 1)

图 1：代理使用工具的一些示例

Fig.1: Some examples of an Agent using Tools

动手实践代码示例（LangChain）

Hands-On Code Example (LangChain)

在 LangChain 框架内实现工具使用是一个两阶段过程。首先，定义一个或多个工具，通常是通过封装现有的 Python 函数或其他可运行组件来实现。随后，将这些工具绑定到语言模型，从而使该模型能够在确定需要调用外部函数来满足用户查询时，生成结构化的工具使用请求。

The implementation of tool use within the LangChain framework is a two-stage process. Initially, one or more tools are defined, typically by encapsulating existing Python functions or other runnable components. Subsequently, these tools are bound to a language model, thereby granting the model the capability to generate a structured tool-use request when it determines that an external function call is required to fulfill a user's query.

以下实现将通过首先定义一个简单的函数来模拟信息检索工具，从而演示这一原理。随后，我们将构建并配置一个代理，使其能够根据用户输入利用该工具。运行此示例需要安装核心 LangChain 库和特定于模型的提供程序包。此外，使用所选语言模型服务进行正确的身份验证（通常通过在本地环境中配置的 API 密钥）也是必要的前提条件。

The following implementation will demonstrate this principle by first defining a simple function to simulate an information retrieval tool. Following this, an agent will be constructed and configured to leverage this tool in response to user input. The execution of this example requires the installation of the core LangChain libraries and a model-specific provider package. Furthermore, proper authentication with the selected language model service, typically via an API key configured in the local environment, is a necessary prerequisite.

import os, getpass import asyncio import nest_asyncio from typing import List from dotenv import load_dotenv import logging from langchain_google_genai import ChatGoogleGenerativeAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.tools import tool as langchain_tool from langchain.agents import create_tool_calling_agent, AgentExecutor # UNCOMMENT # Prompt the user securely and set API keys as an environment variables os.environ["GOOGLE_API_KEY"] = getpass.getpass("Enter your Google API key: ") os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ") try:   # A model with function/tool calling capabilities is required.   llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash", temperature=0)   print(f"✅ Language model initialized: {llm.model}") except Exception as e:   print(f"🛑 Error initializing language model: {e}")   llm = None # --- Define a Tool --- @langchain_tool def search_information(query: str) -> str:   """   Provides factual information on a given topic. Use this tool to find answers to phrases   like 'capital of France' or 'weather in London?'.   """   print(f"\n--- 🛠️ Tool Called: search_information with query: '{query}' ---")   # Simulate a search tool with a dictionary of predefined results.   simulated_results = {       "weather in london": "The weather in London is currently cloudy with a temperature of 15°C.",       "capital of france": "The capital of France is Paris.",       "population of earth": "The estimated population of Earth is around 8 billion people.",       "tallest mountain": "Mount Everest is the tallest mountain above sea level.",       "default": f"Simulated search result for '{query}': No specific information found, but the topic seems interesting."   }   result = simulated_results.get(query.lower(), simulated_results["default"])   print(f"--- TOOL RESULT: {result} ---")   return result tools = [search_information] # --- Create a Tool-Calling Agent --- if llm:   # This prompt template requires an `agent_scratchpad` placeholder for the agent's internal steps.   agent_prompt = ChatPromptTemplate.from_messages([       ("system", "You are a helpful assistant."),       ("human", "{input}"),       ("placeholder", "{agent_scratchpad}"),   ])   # Create the agent, binding the LLM, tools, and prompt together.   agent = create_tool_calling_agent(llm, tools, agent_prompt)   # AgentExecutor is the runtime that invokes the agent and executes the chosen tools.   # The 'tools' argument is not needed here as they are already bound to the agent.   agent_executor = AgentExecutor(agent=agent, verbose=True, tools=tools) async def run_agent_with_tool(query: str):   """Invokes the agent executor with a query and prints the final response."""   print(f"\n--- 🏃 Running Agent with Query: '{query}' ---")   try:       response = await agent_executor.ainvoke({"input": query})       print("\n--- ✅ Final Agent Response ---")       print(response["output"])   except Exception as e:       print(f"\n🛑 An error occurred during agent execution: {e}") async def main():   """Runs all agent queries concurrently."""   tasks = [       run_agent_with_tool("What is the capital of France?"),       run_agent_with_tool("What's the weather like in London?"),       run_agent_with_tool("Tell me something about dogs.") # Should trigger the default tool response   ]   await asyncio.gather(*tasks) nest_asyncio.apply() asyncio.run(main())

该代码使用 LangChain 库和 Google Gemini 模型设置了一个工具调用代理。它定义了一个名为 search_information 的工具，该工具模拟为特定查询提供事实性答案。该工具预定义了“伦敦天气”、“法国首都”和“地球人口”的响应，并为其他查询提供了一个默认响应。代码初始化了一个 ChatGoogleGenerativeAI 模型，确保其具备工具调用能力。此外，还创建了一个 ChatPromptTemplate 来指导代理的交互。create_tool_calling_agent 函数用于将语言模型、工具和提示信息组合成一个代理。然后，设置了一个 AgentExecutor 来管理代理的执行和工具调用。run_agent_with_tool 异步函数用于使用给定的查询调用代理并打印结果。主异步函数准备多个要并发运行的查询。这些查询旨在测试 search_information 工具的特定响应和默认响应。最后，asyncio.run(main()) 调用执行所有代理任务。该代码在进行代理设置和执行之前，会检查 LLM 初始化是否成功。

The code sets up a tool-calling agent using the LangChain library and the Google Gemini model. It defines a search_information tool that simulates providing factual answers to specific queries. The tool has predefined responses for "weather in london," "capital of france," and "population of earth," and a default response for other queries. A ChatGoogleGenerativeAI model is initialized, ensuring it has tool-calling capabilities. A ChatPromptTemplate is created to guide the agent's interaction. The create_tool_calling_agent function is used to combine the language model, tools, and prompt into an agent. An AgentExecutor is then set up to manage the agent's execution and tool invocation. The run_agent_with_tool asynchronous function is defined to invoke the agent with a given query and print the result. The main asynchronous function prepares multiple queries to be run concurrently. These queries are designed to test both the specific and default responses of the search_information tool. Finally, the asyncio.run(main()) call executes all the agent tasks. The code includes checks for successful LLM initialization before proceeding with agent setup and execution.

动手实践代码示例（CrewAI）

Hands-On Code Example (CrewAI)

这段代码提供了一个在 CrewAI 框架内实现函数调用（工具）的实际示例。它设置了一个简单的场景，其中智能体配备了一个用于查找信息的工具。该示例具体演示了如何使用该智能体和工具获取模拟股票价格。

This code provides a practical example of how to implement function calling (Tools) within the CrewAI framework. It sets up a simple scenario where an agent is equipped with a tool to look up information. The example specifically demonstrates fetching a simulated stock price using this agent and tool.

# pip install crewai langchain-openai import os from crewai import Agent, Task, Crew from crewai.tools import tool import logging # --- Best Practice: Configure Logging --- # A basic logging setup helps in debugging and tracking the crew's execution. logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s') # --- Set up your API Key --- # For production, it's recommended to use a more secure method for key management # like environment variables loaded at runtime or a secret manager. # # Set the environment variable for your chosen LLM provider (e.g., OPENAI_API_KEY) # os.environ["OPENAI_API_KEY"] = "YOUR_API_KEY" # os.environ["OPENAI_MODEL_NAME"] = "gpt-4o" # --- 1. Refactored Tool: Returns Clean Data --- # The tool now returns raw data (a float) or raises a standard Python error. # This makes it more reusable and forces the agent to handle outcomes properly. @tool("Stock Price Lookup Tool") def get_stock_price(ticker: str) -> float:    """    Fetches the latest simulated stock price for a given stock ticker symbol.    Returns the price as a float. Raises a ValueError if the ticker is not found.    """    logging.info(f"Tool Call: get_stock_price for ticker '{ticker}'")    simulated_prices = {        "AAPL": 178.15,         "GOOGL": 1750.30,        "MSFT": 425.50,    }    price = simulated_prices.get(ticker.upper())    if price is not None:        return price    else:        # Raising a specific error is better than returning a string.        # The agent is equipped to handle exceptions and can decide on the next action.        raise ValueError(f"Simulated price for ticker '{ticker.upper()}' not found.") # --- 2. Define the Agent --- # The agent definition remains the same, but it will now leverage the improved tool. financial_analyst_agent = Agent(  role='Senior Financial Analyst',  goal='Analyze stock data using provided tools and report key prices.',  backstory="You are an experienced financial analyst adept at using data sources to find stock information. You provide clear, direct answers.",  verbose=True,  tools=[get_stock_price],  # Allowing delegation can be useful, but is not necessary for this simple task.  allow_delegation=False, ) # --- 3. Refined Task: Clearer Instructions and Error Handling --- # The task description is more specific and guides the agent on how to react # to both successful data retrieval and potential errors. analyze_aapl_task = Task(  description=(      "What is the current simulated stock price for Apple (ticker: AAPL)? "      "Use the 'Stock Price Lookup Tool' to find it. "      "If the ticker is not found, you must report that you were unable to retrieve the price."  ),  expected_output=(      "A single, clear sentence stating the simulated stock price for AAPL. "      "For example: 'The simulated stock price for AAPL is $178.15.' "      "If the price cannot be found, state that clearly."  ),  agent=financial_analyst_agent, ) # --- 4. Formulate the Crew --- # The crew orchestrates how the agent and task work together. financial_crew = Crew(  agents=[financial_analyst_agent],  tasks=[analyze_aapl_task],  verbose=True # Set to False for less detailed logs in production ) # --- 5. Run the Crew within a Main Execution Block --- # Using a __name__ == "__main__": block is a standard Python best practice. def main():    """Main function to run the crew."""    # Check for API key before starting to avoid runtime errors.    if not os.environ.get("OPENAI_API_KEY"):        print("ERROR: The OPENAI_API_KEY environment variable is not set.")        print("Please set it before running the script.")        return    print("\n## Starting the Financial Crew...")    print("---------------------------------")      # The kickoff method starts the execution.    result = financial_crew.kickoff()    print("\n---------------------------------")    print("## Crew execution finished.")    print("\nFinal Result:\n", result) if __name__ == "__main__":    main()

这段代码演示了一个使用 Crew.ai 库模拟财务分析任务的简单应用程序。它定义了一个名为 `get_stock_price` 的自定义工具，用于模拟查找预定义股票代码的股价。该工具的设计是：对于有效的股票代码返回一个浮点数，对于无效的股票代码则抛出一个 `ValueError` 异常。创建了一个名为 `financial_analyst_agent` 的 Crew.ai 代理，并将其角色设置为高级财务分析师。该代理被赋予了 `get_stock_price` 工具进行交互。定义了一个名为 `analyze_aapl_task` 的任务，明确指示代理使用该工具查找 AAPL 的模拟股价。任务描述包含了关于如何处理使用该工具时的成功和失败情况的清晰说明。构建了一个包含 `financial_analyst_agent` 和 `analyze_aapl_task` 的 Crew。代理和 Crew 都启用了详细日志记录，以便在执行过程中提供详细的日志信息。脚本的主要部分使用 `kickoff()` 方法在标准的 `if __name__ == "__main__":` 代码块中运行 Crew 的任务。在启动团队之前，它会检查是否已设置 OPENAI_API_KEY 环境变量，这是代理正常运行所必需的。团队执行结果（即任务输出）随后会打印到控制台。代码还包含基本的日志配置，以便更好地跟踪团队的操作和工具调用。它使用环境变量进行 API 密钥管理，但指出建议在生产环境中使用更安全的方法。简而言之，核心逻辑展示了如何在 Crew.ai 中定义工具、代理和任务，从而创建协作工作流程。

This code demonstrates a simple application using the Crew.ai library to simulate a financial analysis task. It defines a custom tool, get_stock_price, that simulates looking up stock prices for predefined tickers. The tool is designed to return a floating-point number for valid tickers or raise a ValueError for invalid ones. A Crew.ai Agent named financial_analyst_agent is created with the role of a Senior Financial Analyst. This agent is given the get_stock_price tool to interact with. A Task is defined, analyze_aapl_task, specifically instructing the agent to find the simulated stock price for AAPL using the tool. The task description includes clear instructions on how to handle both success and failure cases when using the tool. A Crew is assembled, comprising the financial_analyst_agent and the analyze_aapl_task. The verbose setting is enabled for both the agent and the crew to provide detailed logging during execution. The main part of the script runs the crew's task using the kickoff() method within a standard if __name__ == "__main__": block. Before starting the crew, it checks if the OPENAI_API_KEY environment variable is set, which is required for the agent to function. The result of the crew's execution, which is the output of the task, is then printed to the console. The code also includes basic logging configuration for better tracking of the crew's actions and tool calls. It uses environment variables for API key management, though it notes that more secure methods are recommended for production environments. In short, the core logic showcases how to define tools, agents, and tasks to create a collaborative workflow in Crew.ai.

动手写代码（Google ADK）

Hands-on code (Google ADK)

Google Agent Developer Kit (ADK) 包含一个原生集成工具库，可以直接将其集成到代理的功能中。

The Google Agent Developer Kit (ADK) includes a library of natively integrated tools that can be directly incorporated into an agent's capabilities.

谷歌搜索：  此类组件的一个典型例子是谷歌搜索工具。该工具作为谷歌搜索引擎的直接接口，使代理能够执行网络搜索并检索外部信息。

Google search:  A primary example of such a component is the Google Search tool. This tool serves as a direct interface to the Google Search engine, equipping the agent with the functionality to perform web searches and retrieve external information.

from google.adk.agents import Agent from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService from google.adk.tools import google_search from google.genai import types import nest_asyncio import asyncio # Define variables required for Session setup and Agent execution APP_NAME="Google Search_agent" USER_ID="user1234" SESSION_ID="1234" # Define Agent with access to search tool root_agent = ADKAgent(   name="basic_search_agent",   model="gemini-2.0-flash-exp",   description="Agent to answer questions using Google Search.",   instruction="I can answer your questions by searching the internet. Just ask me anything!",   tools=[google_search] # Google Search is a pre-built tool to perform Google searches. ) # Agent Interaction async def call_agent(query):   """   Helper function to call the agent with a query.   """   # Session and Runner   session_service = InMemorySessionService()   session = await session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID)   runner = Runner(agent=root_agent, app_name=APP_NAME, session_service=session_service)   content = types.Content(role='user', parts=[types.Part(text=query)])   events = runner.run(user_id=USER_ID, session_id=SESSION_ID, new_message=content)   for event in events:       if event.is_final_response():           final_response = event.content.parts[0].text           print("Agent Response: ", final_response) nest_asyncio.apply() asyncio.run(call_agent("what's the latest ai news?"))

这段代码演示了如何创建和使用基于 Google ADK for Python 的基本代理。该代理旨在利用 Google 搜索作为工具来回答问题。首先，导入必要的库，包括 IPython、google.adk 和 google.genai。定义了应用程序名称、用户 ID 和会话 ID 等常量。创建了一个名为“basic_search_agent”的代理实例，并为其添加了描述和说明，以明确其用途。该代理配置为使用 Google 搜索工具，这是 ADK 提供的预构建工具。初始化一个 InMemorySessionService（参见第 8 章）来管理代理的会话。为指定的应用程序 ID、用户 ID 和会话 ID 创建一个新会话。实例化一个 Runner，将创建的代理与会话服务连接起来。该 Runner 负责在会话中执行代理的交互操作。定义了一个辅助函数 call_agent，以简化向代理发送查询和处理响应的过程。在 `call_agent` 函数内部，用户的查询被格式化为一个类型为 `types.Content` 的对象，角色为 `'user'`。`runner.run` 方法被调用，并传入用户 ID、会话 ID 和新消息内容。`runner.run` 方法返回一个事件列表，该列表代表代理的操作和响应。代码遍历这些事件以查找最终响应。如果某个事件被识别为最终响应，则提取该响应的文本内容。提取的代理响应随后被打印到控制台。最后，使用查询“最新的 AI 新闻是什么？”调用 `call_agent` 函数，以演示代理的运行情况。

This code demonstrates how to create and use a basic agent powered by the Google ADK for Python. The agent is designed to answer questions by utilizing Google Search as a tool. First, necessary libraries from IPython, google.adk, and google.genai are imported. Constants for the application name, user ID, and session ID are defined. An Agent instance named "basic_search_agent" is created with a description and instructions indicating its purpose. It's configured to use the Google Search tool, which is a pre-built tool provided by the ADK. An InMemorySessionService (see Chapter 8) is initialized to manage sessions for the agent. A new session is created for the specified application, user, and session IDs. A Runner is instantiated, linking the created agent with the session service. This runner is responsible for executing the agent's interactions within a session. A helper function call_agent is defined to simplify the process of sending a query to the agent and processing the response. Inside call_agent, the user's query is formatted as a types.Content object with the role 'user'. The runner.run method is called with the user ID, session ID, and the new message content. The runner.run method returns a list of events representing the agent's actions and responses. The code iterates through these events to find the final response. If an event is identified as the final response, the text content of that response is extracted. The extracted agent response is then printed to the console. Finally, the call_agent function is called with the query "what's the latest ai news?" to demonstrate the agent in action.

代码执行： Google ADK 集成了用于特定任务的组件，包括一个动态代码执行环境。内置的 `built_in_code_execution` 工具为代理提供了一个沙盒化的 Python 解释器。这使得模型能够编写和运行代码来执行计算任务、操作数据结构以及执行过程脚本。这种功能对于解决需要确定性逻辑和精确 计算的问题至关重要 ，而这些问题仅靠概率语言生成是无法解决的。

Code execution: The Google ADK features integrated components for specialized tasks, including an environment for dynamic code execution. The built_in_code_execution tool provides an agent with a sandboxed Python interpreter. This allows the model to write and run code to perform computational tasks, manipulate data structures, and execute procedural scripts. Such functionality is critical for addressing problems that require deterministic logic and precise calculations , which are outside the scope of probabilistic language generation alone.

import os, getpass import asyncio import nest_asyncio from typing import List from dotenv import load_dotenv import logging from google.adk.agents import Agent as ADKAgent, LlmAgent from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService from google.adk.tools import google_search from google.adk.code_executors import BuiltInCodeExecutor from google.genai import types # Define variables required for Session setup and Agent execution APP_NAME="calculator" USER_ID="user1234" SESSION_ID="session_code_exec_async" # Agent Definition code_agent = LlmAgent(   name="calculator_agent",   model="gemini-2.0-flash",   code_executor=BuiltInCodeExecutor(),   instruction="""You are a calculator agent.   When given a mathematical expression, write and execute Python code to calculate the result.   Return only the final numerical result as plain text, without markdown or code blocks.   """,   description="Executes Python code to perform calculations.", ) # Agent Interaction (Async) async def call_agent_async(query):   # Session and Runner   session_service = InMemorySessionService()   session = await session_service.create_session(app_name=APP_NAME, user_id=USER_ID, session_id=SESSION_ID)   runner = Runner(agent=code_agent, app_name=APP_NAME, session_service=session_service)   content = types.Content(role='user', parts=[types.Part(text=query)])   print(f"\n--- Running Query: {query} ---")   final_response_text = "No final text response captured."   try:       # Use run_async       async for event in runner.run_async(user_id=USER_ID, session_id=SESSION_ID, new_message=content):           print(f"Event ID: {event.id}, Author: {event.author}")           # --- Check for specific parts FIRST ---           # has_specific_part = False           if event.content and event.content.parts and event.is_final_response():               for part in event.content.parts: # Iterate through all parts                   if part.executable_code:                       # Access the actual code string via .code                       print(f"  Debug: Agent generated code:\n```python\n{part.executable_code.code}\n```")                       has_specific_part = True                   elif part.code_execution_result:                       # Access outcome and output correctly                       print(f"  Debug: Code Execution Result: {part.code_execution_result.outcome} - Output:\n{part.code_execution_result.output}")                       has_specific_part = True                   # Also print any text parts found in any event for debugging                   elif part.text and not part.text.isspace():                       print(f"  Text: '{part.text.strip()}'")                       # Do not set has_specific_part=True here, as we want the final response logic below               # --- Check for final response AFTER specific parts ---               text_parts = [part.text for part in event.content.parts if part.text]               final_result = "".join(text_parts)               print(f"==> Final Agent Response: {final_result}")   except Exception as e:       print(f"ERROR during agent run: {e}")   print("-" * 30) # Main async function to run the examples async def main():   await call_agent_async("Calculate the value of (5 + 7) * 3")   await call_agent_async("What is 10 factorial?") # Execute the main async function try:   nest_asyncio.apply()   asyncio.run(main()) except RuntimeError as e:   # Handle specific error when running asyncio.run in an already running loop (like Jupyter/Colab)   if "cannot be called from a running event loop" in str(e):       print("\nRunning in an existing event loop (like Colab/Jupyter).")       print("Please run `await main()` in a notebook cell instead.")       # If in an interactive environment like a notebook, you might need to run:       # await main()   else:       raise e # Re-raise other runtime errors

此脚本使用 Google 的代理开发工具包 (ADK) 创建一个代理，该代理通过编写和执行 Python 代码来解决数学问题。它定义了一个 LlmAgent，专门用于充当计算器，并为其配备了内置的 `built_in_code_execution` 工具。主要逻辑位于 `call_agent_async` 函数中，该函数将用户的查询发送到代理的运行器并处理生成的事件。在该函数内部，一个异步循环遍历事件，打印生成的 Python 代码及其执行结果以进行调试。代码仔细区分了这些中间步骤和包含数值答案的最终事件。最后，主函数使用两个不同的数学表达式运行代理，以演示其计算能力。

This script uses Google's Agent Development Kit (ADK) to create an agent that solves mathematical problems by writing and executing Python code. It defines an LlmAgent specifically instructed to act as a calculator, equipping it with the built_in_code_execution tool. The primary logic resides in the call_agent_async function, which sends a user's query to the agent's runner and processes the resulting events. Inside this function, an asynchronous loop iterates through events, printing the generated Python code and its execution result for debugging. The code carefully distinguishes between these intermediate steps and the final event containing the numerical answer. Finally, a main function runs the agent with two different mathematical expressions to demonstrate its ability to perform calculations.

企业搜索： 此代码使用 Python 中的 google.adk 库定义了一个 Google ADK 应用程序。它具体使用了 VSearchAgent，该代理旨在通过搜索指定的 Vertex AI 搜索数据存储来回答问题。代码初始化了一个名为“q2_strategy_vsearch_agent”的 VSearchAgent，并为其提供了描述、要使用的模型（“gemini-2.0-flash-exp”）以及 Vertex AI 搜索数据存储的 ID。DATASTORE_ID 需要设置为环境变量。然后，它为代理设置了一个 Runner，并使用 InMemorySessionService 来管理会话历史记录。定义了一个异步函数 call_vsearch_agent_async 来与代理交互。此函数接收一个查询，构建一个消息内容对象，并调用 Runner 的 run_async 方法将查询发送给代理。然后，该函数将代理的响应实时流式传输回控制台。它还会打印有关最终响应的信息，包括来自数据存储的任何来源归属信息。错误处理机制用于捕获代理执行过程中出现的异常，并提供有关潜在问题（例如数据存储 ID 错误或权限缺失）的提示信息。此外，还提供了一个异步函数 `run_vsearch_example`，用于演示如何使用示例查询调用代理。主执行块会检查 `DATASTORE_ID` 是否已设置，然后使用 `asyncio.run` 运行示例。它还包含一项检查，用于处理代码在已运行事件循环的环境（例如 Jupyter notebook）中运行的情况。

Enterprise search: This code defines a Google ADK application using the google.adk library in Python. It specifically uses a VSearchAgent, which is designed to answer questions by searching a specified Vertex AI Search datastore. The code initializes a VSearchAgent named "q2_strategy_vsearch_agent", providing a description, the model to use ("gemini-2.0-flash-exp"), and the ID of the Vertex AI Search datastore. The DATASTORE_ID is expected to be set as an environment variable. It then sets up a Runner for the agent, using an InMemorySessionService to manage conversation history. An asynchronous function call_vsearch_agent_async is defined to interact with the agent. This function takes a query, constructs a message content object, and calls the runner's run_async method to send the query to the agent. The function then streams the agent's response back to the console as it arrives. It also prints information about the final response, including any source attributions from the datastore. Error handling is included to catch exceptions during the agent's execution, providing informative messages about potential issues like an incorrect datastore ID or missing permissions. Another asynchronous function run_vsearch_example is provided to demonstrate how to call the agent with example queries. The main execution block checks if the DATASTORE_ID is set and then runs the example using asyncio.run. It includes a check to handle cases where the code is run in an environment that already has a running event loop, like a Jupyter notebook.

import asyncio from google.genai import types from google.adk import agents from google.adk.runners import Runner from google.adk.sessions import InMemorySessionService import os # --- Configuration --- # Ensure you have set your GOOGLE_API_KEY and DATASTORE_ID environment variables # For example: # os.environ["GOOGLE_API_KEY"] = "YOUR_API_KEY" # os.environ["DATASTORE_ID"] = "YOUR_DATASTORE_ID" DATASTORE_ID = os.environ.get("DATASTORE_ID") # --- Application Constants --- APP_NAME = "vsearch_app" USER_ID = "user_123"  # Example User ID SESSION_ID = "session_456" # Example Session ID # --- Agent Definition (Updated with the newer model from the guide) --- vsearch_agent = agents.VSearchAgent(    name="q2_strategy_vsearch_agent",    description="Answers questions about Q2 strategy documents using Vertex AI Search.",    model="gemini-2.0-flash-exp", # Updated model based on the guide's examples    datastore_id=DATASTORE_ID,    model_parameters={"temperature": 0.0} ) # --- Runner and Session Initialization --- runner = Runner(    agent=vsearch_agent,    app_name=APP_NAME,    session_service=InMemorySessionService(), ) # --- Agent Invocation Logic --- async def call_vsearch_agent_async(query: str):    """Initializes a session and streams the agent's response."""    print(f"User: {query}")    print("Agent: ", end="", flush=True)    try:        # Construct the message content correctly        content = types.Content(role='user', parts=[types.Part(text=query)])        # Process events as they arrive from the asynchronous runner        async for event in runner.run_async(            user_id=USER_ID,            session_id=SESSION_ID,            new_message=content        ):            # For token-by-token streaming of the response text            if hasattr(event, 'content_part_delta') and event.content_part_delta:                print(event.content_part_delta.text, end="", flush=True)            # Process the final response and its associated metadata            if event.is_final_response():                print() # Newline after the streaming response                if event.grounding_metadata:                    print(f"  (Source Attributions: {len(event.grounding_metadata.grounding_attributions)} sources found)")                else:                    print("  (No grounding metadata found)")                print("-" * 30)    except Exception as e:        print(f"\nAn error occurred: {e}")        print("Please ensure your datastore ID is correct and that the service account has the necessary permissions.")        print("-" * 30) # --- Run Example --- async def run_vsearch_example():    # Replace with a question relevant to YOUR datastore content    await call_vsearch_agent_async("Summarize the main points about the Q2 strategy document.")    await call_vsearch_agent_async("What safety procedures are mentioned for lab X?") # --- Execution --- if __name__ == "__main__":    if not DATASTORE_ID:        print("Error: DATASTORE_ID environment variable is not set.")    else:        try:            asyncio.run(run_vsearch_example())        except RuntimeError as e:            # This handles cases where asyncio.run is called in an environment            # that already has a running event loop (like a Jupyter notebook).            if "cannot be called from a running event loop" in str(e):                print("Skipping execution in a running event loop. Please run this script directly.")            else:                raise e

总的来说，这段代码提供了一个构建对话式 AI 应用的基本框架，该应用利用 Vertex AI Search 根据数据存储中存储的信息来回答问题。它演示了如何定义代理、设置运行器，以及如何在异步流式传输响应的同时与代理进行交互。重点在于从特定的数据存储中检索和综合信息以回答用户查询。

Overall, this code provides a basic framework for building a conversational AI application that leverages Vertex AI Search to answer questions based on information stored in a datastore. It demonstrates how to define an agent, set up a runner, and interact with the agent asynchronously while streaming the response. The focus is on retrieving and synthesizing information from a specific datastore to answer user queries.

Vertex 扩展：  Vertex AI 扩展是一种结构化的 API 封装器，它使模型能够连接外部 API，从而实现实时数据处理和操作执行。扩展提供企业级安全性、数据隐私和性能保障。它们可用于生成和运行代码、查询网站以及分析私有数据存储中的信息等任务。Google 为常见用例（例如代码解释器和 Vertex AI 搜索）提供了预构建的扩展，用户也可以创建自定义扩展。扩展的主要优势在于强大的企业级控制以及与其他 Google 产品的无缝集成。扩展和函数调用之间的主要区别在于它们的执行方式：Vertex AI 会自动执行扩展，而函数调用则需要用户或客户端手动执行。

Vertex Extensions:  A Vertex AI extension is a structured API wrapper that enables a model to connect with external APIs for real-time data processing and action execution. Extensions offer enterprise-grade security, data privacy, and performance guarantees. They can be used for tasks like generating and running code, querying websites, and analyzing information from private datastores. Google provides prebuilt extensions for common use cases like Code Interpreter and Vertex AI Search, with the option to create custom ones. The primary benefit of extensions includes strong enterprise controls and seamless integration with other Google products. The key difference between extensions and function calling lies in their execution: Vertex AI automatically executes extensions, whereas function calls require manual execution by the user or client.

概览

At a Glance

问题：  逻辑学习模型（LLM）功能强大，能够生成文本，但它们与外部世界存在根本性的脱节。它们的知识是静态的，仅限于训练时所用的数据，并且缺乏执行操作或获取实时信息的能力。这种固有的局限性使得它们无法完成需要与外部API、数据库或服务交互的任务。如果没有与这些外部系统的连接，它们在解决实际问题方面的效用将受到严重限制。

What:  LLMs are powerful text generators, but they are fundamentally disconnected from the outside world. Their knowledge is static, limited to the data they were trained on, and they lack the ability to perform actions or retrieve real-time information. This inherent limitation prevents them from completing tasks that require interaction with external APIs, databases, or services. Without a bridge to these external systems, their utility for solving real-world problems is severely constrained.

原因：  工具使用模式（通常通过函数调用实现）为该问题提供了一种标准化的解决方案。其工作原理是向生命周期管理（LLM）描述可用的外部函数或“工具”，使其能够理解。基于用户的请求，代理型LLM可以判断是否需要某个工具，并生成一个结构化数据对象（例如JSON），其中指定要调用的函数及其参数。编排层执行此函数调用，检索结果，并将其反馈给LLM。这使得LLM能够将最新的外部信息或操作结果整合到其最终响应中，从而有效地赋予其执行操作的能力。

Why:  The Tool Use pattern, often implemented via function calling, provides a standardized solution to this problem. It works by describing available external functions, or "tools," to the LLM in a way it can understand. Based on a user's request, the agentic LLM can then decide if a tool is needed and generate a structured data object (like a JSON) specifying which function to call and with what arguments. An orchestration layer executes this function call, retrieves the result, and feeds it back to the LLM. This allows the LLM to incorporate up-to-date, external information or the result of an action into its final response, effectively giving it the ability to act.

经验法则：  当智能体需要突破LLM的内部知识限制并与外部世界交互时，应使用工具使用模式。这对于需要实时数据（例如，查看天气、股票价格）、访问私有或专有信息（例如，查询公司数据库）、执行精确计算、执行代码或触发其他系统中的操作（例如，发送电子邮件、控制智能设备）的任务至关重要。

Rule of thumb:  Use the Tool Use pattern whenever an agent needs to break out of the LLM's internal knowledge and interact with the outside world. This is essential for tasks requiring real-time data (e.g., checking weather, stock prices), accessing private or proprietary information (e.g., querying a company's database), performing precise calculations, executing code, or triggering actions in other systems (e.g., sending an email, controlling smart devices).

可视化概要：

Visual summary:

图2：工具使用设计模式

Fig.2: Tool use design pattern

要点总结

Key Takeaways

• 工具使用（函数调用）允许代理与外部系统交互并访问动态信息。
• Tool Use (Function Calling) allows agents to interact with external systems and access dynamic information.
• 这包括定义具有清晰描述和参数的工具，以便LLM能够理解。
• It involves defining tools with clear descriptions and parameters that the LLM can understand.
• LLM 决定何时使用工具并生成结构化函数调用。
• The LLM decides when to use a tool and generates structured function calls.
• 代理框架执行实际的工具调用并将结果返回给 LLM。
• Agentic frameworks execute the actual tool calls and return the results to the LLM.
• 工具的使用对于构建能够执行现实世界操作并提供最新信息的智能体至关重要。
• Tool Use is essential for building agents that can perform real-world actions and provide up-to-date information.
• LangChain 使用 @tool 装饰器简化了工具定义，并提供了 create_tool_calling_agent 和 AgentExecutor 来构建使用工具的代理。
• LangChain simplifies tool definition using the @tool decorator and provides create_tool_calling_agent and AgentExecutor for building tool-using agents.
• Google ADK 拥有许多非常有用的预构建工具，例如 Google 搜索、代码执行和 Vertex AI 搜索工具。
• Google ADK has a number of very useful pre-built tools such as Google Search, Code Execution and Vertex AI Search Tool.

结论

Conclusion

工具使用模式是扩展大型语言模型功能范围的关键架构原则，使其超越了固有的文本生成能力。通过赋予模型与外部软件和数据源交互的能力，该范式允许智能体执行操作、进行计算并从其他系统检索信息。此过程涉及模型在确定需要调用外部工具来满足用户查询时，生成结构化的调用请求。LangChain、Google ADK 和 Crew AI 等框架提供了结构化的抽象和组件，便于集成这些外部工具。这些框架管理着向模型公开工具规范并解析其后续工具使用请求的过程。这简化了能够与外部数字环境交互并在其中执行操作的复杂智能体的开发。

The Tool Use pattern is a critical architectural principle for extending the functional scope of large language models beyond their intrinsic text generation capabilities. By equipping a model with the ability to interface with external software and data sources, this paradigm allows an agent to perform actions, execute computations, and retrieve information from other systems. This process involves the model generating a structured request to call an external tool when it determines that doing so is necessary to fulfill a user's query. Frameworks such as LangChain, Google ADK, and Crew AI offer structured abstractions and components that facilitate the integration of these external tools. These frameworks manage the process of exposing tool specifications to the model and parsing its subsequent tool-use requests. This simplifies the development of sophisticated agentic systems that can interact with and take action within external digital environments.

参考

References

1. LangChain 文档（工具）： https://python.langchain.com/docs/integrations/tools/  
2. LangChain Documentation (Tools): https://python.langchain.com/docs/integrations/tools/  
3. Google Agent Developer Kit (ADK) 文档（工具）： https://google.github.io/adk-docs/tools/  
4. Google Agent Developer Kit (ADK) Documentation (Tools): https://google.github.io/adk-docs/tools/  
5. OpenAI 函数调用文档： https://platform.openai.com/docs/guides/function-calling  
6. OpenAI Function Calling Documentation: https://platform.openai.com/docs/guides/function-calling  
7. CrewAI 文档（工具）： https://docs.crewai.com/concepts/tools  
8. CrewAI Documentation (Tools): https://docs.crewai.com/concepts/tools  

第六章：规划

Chapter 6: Planning

智能行为通常不仅仅是对即时输入做出反应。它需要预见性，将复杂任务分解成更小、更易于管理的步骤，并制定策略来实现预期结果。这就是规划模式发挥作用的地方。规划的核心在于智能体或智能体系统能够制定一系列行动方案，从而从初始状态过渡到目标状态。

Intelligent behavior often involves more than just reacting to the immediate input. It requires foresight, breaking down complex tasks into smaller, manageable steps, and strategizing how to achieve a desired outcome. This is where the Planning pattern comes into play. At its core, planning is the ability for an agent or a system of agents to formulate a sequence of actions to move from an initial state towards a goal state.

规划模式概述

Planning Pattern Overview

在人工智能领域，我们可以将规划代理想象成一位专家，您可以将一项复杂的任务委托给他。例如，当您要求它“组织一次团队拓展活动”时，您定义了“做什么”——目标及其约束条件——但并未定义“怎么做”。代理的核心任务是自主规划实现目标的路线。它必须首先了解初始状态（例如预算、参与人数、期望日期）和目标状态（成功预订拓展活动），然后找出连接两者的最佳行动顺序。计划并非预先设定，而是根据请求自动生成。

In the context of AI, it's helpful to think of a planning agent as a specialist to whom you delegate a complex goal. When you ask it to "organize a team offsite," you are defining the what—the objective and its constraints—but not the how. The agent's core task is to autonomously chart a course to that goal. It must first understand the initial state (e.g., budget, number of participants, desired dates) and the goal state (a successfully booked offsite), and then discover the optimal sequence of actions to connect them. The plan is not known in advance; it is created in response to the request.

这一过程的显著特点是适应性。初始计划仅仅是一个起点，而非僵化的剧本。代理人的真正实力在于其整合新信息并引导项目绕过障碍的能力。例如，如果首选场地无法使用或选定的餐饮供应商已满，一位称职的代理人不会就此放弃。它会做出调整。它会记录新的限制条件，重新评估各种方案，并制定新的计划，例如建议其他场地或日期。

A hallmark of this process is adaptability. An initial plan is merely a starting point, not a rigid script. The agent's real power is its ability to incorporate new information and steer the project around obstacles. For instance, if the preferred venue becomes unavailable or a chosen caterer is fully booked, a capable agent doesn't simply fail. It adapts. It registers the new constraint, re-evaluates its options, and formulates a new plan, perhaps by suggesting alternative venues or dates.

然而，认识到灵活性和可预测性之间的权衡至关重要。动态规划是一种特定的工具，而非通用的解决方案。当问题的解决方案已被充分理解且可重复时，将智能体限制在预先设定的固定工作流程中更为有效。这种方法限制了智能体的自主性，从而降低了不确定性和不可预测行为的风险，确保了结果的可靠性和一致性。因此，选择使用规划智能体还是简单的任务执行智能体，关键在于一个问题：是否需要探索“如何做”，还是它已经为人所知？

However, it is crucial to recognize the trade-off between flexibility and predictability. Dynamic planning is a specific tool, not a universal solution. When a problem's solution is already well-understood and repeatable, constraining the agent to a predetermined, fixed workflow is more effective. This approach limits the agent's autonomy to reduce uncertainty and the risk of unpredictable behavior, guaranteeing a reliable and consistent outcome. Therefore, the decision to use a planning agent versus a simple task-execution agent hinges on a single question: does the "how" need to be discovered, or is it already known?

实际应用及案例

Practical Applications & Use Cases

规划模式是自主系统中的核心计算过程，它使智能体能够综合一系列动作以实现特定目标，尤其是在动态或复杂的环境中。该过程将高层目标转化为由离散、可执行步骤组成的结构化计划。

The Planning pattern is a core computational process in autonomous systems, enabling an agent to synthesize a sequence of actions to achieve a specified goal, particularly within dynamic or complex environments. This process transforms a high-level objective into a structured plan composed of discrete, executable steps.

在流程任务自动化等领域，规划用于协调复杂的流程。例如，像 新员工入职这样的业务流程可以分解为一系列有方向的子任务 ，例如创建系统账户、分配培训模块以及与不同部门协调。代理会生成一个计划，按逻辑顺序执行这些步骤，并调用必要的工具或与各种系统交互以管理依赖关系。

In domains such as procedural task automation, planning is used to orchestrate complex workflows. For example, a business process like onboarding a new employee can be decomposed into a directed sequence of sub-tasks , such as creating system accounts, assigning training modules, and coordinating with different departments. The agent generates a plan to execute these steps in a logical order, invoking necessary tools or interacting with various systems to manage dependencies.

在机器人和自主导航领域，规划是状态空间遍历的基础。无论是物理机器人还是虚拟实体，系统都必须生成一条路径或一系列动作，才能从初始状态过渡到目标状态。这需要在满足环境约束（例如避开障碍物或遵守交通规则）的同时，优化诸如时间或能耗等指标。

Within robotics and autonomous navigation, planning is fundamental for state-space traversal. A system, whether a physical robot or a virtual entity, must generate a path or sequence of actions to transition from an initial state to a goal state. This involves optimizing for metrics such as time or energy consumption while adhering to environmental constraints, like avoiding obstacles or following traffic regulations.

这种模式对于结构化信息综合也至关重要。当需要生成类似研究报告的复杂输出时，客服人员可以制定一个包含信息收集、数据汇总、内容结构化和迭代完善等不同阶段的计划。同样，在涉及多步骤问题解决的客户支持场景中，客服人员可以创建并遵循一套系统化的诊断、解决方案实施和升级流程。

This pattern is also critical for structured information synthesis. When tasked with generating a complex output like a research report, an agent can formulate a plan that includes distinct phases for information gathering, data summarization, content structuring, and iterative refinement. Similarly, in customer support scenarios involving multi-step problem resolution, an agent can create and follow a systematic plan for diagnosis, solution implementation, and escalation.

本质上，规划模式使智能体能够超越简单的被动反应，转向目标导向的行为。它提供了一个必要的逻辑框架，用于解决需要一系列相互依存的连贯操作的问题。

In essence, the Planning pattern allows an agent to move beyond simple, reactive actions to goal-oriented behavior. It provides the logical framework necessary to solve problems that require a coherent sequence of interdependent operations.

动手实践代码（ 船员人工智能 ）

Hands-on code ( Crew AI )

以下部分将演示如何使用 Crew AI 框架实现规划器模式。该模式包含一个代理，它首先制定一个多步骤计划来解决复杂的查询，然后按顺序执行该计划。

The following section will demonstrate an implementation of the Planner pattern using the Crew AI framework. This pattern involves an agent that first formulates a multi-step plan to address a complex query and then executes that plan sequentially.

import os from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from langchain_openai import ChatOpenAI # Load environment variables from .env file for security load_dotenv() # 1. Explicitly define the language model for clarity llm = ChatOpenAI(model="gpt-4-turbo") # 2. Define a clear and focused agent planner_writer_agent = Agent(    role='Article Planner and Writer',    goal='Plan and then write a concise, engaging summary on a specified topic.',    backstory=(        'You are an expert technical writer and content strategist. '        'Your strength lies in creating a clear, actionable plan before writing, '        'ensuring the final summary is both informative and easy to digest.'    ),    verbose=True,    allow_delegation=False,    llm=llm # Assign the specific LLM to the agent ) # 3. Define a task with a more structured and specific expected output topic = "The importance of Reinforcement Learning in AI" high_level_task = Task(    description=(        f"1. Create a bullet-point plan for a summary on the topic: '{topic}'.\n"        f"2. Write the summary based on your plan, keeping it around 200 words."    ),    expected_output=(        "A final report containing two distinct sections:\n\n"        "### Plan\n"        "- A bulleted list outlining the main points of the summary.\n\n"        "### Summary\n"        "- A concise and well-structured summary of the topic."    ),    agent=planner_writer_agent, ) # Create the crew with a clear process crew = Crew(    agents=[planner_writer_agent],    tasks=[high_level_task],    process=Process.sequential, ) # Execute the task print("## Running the planning and writing task ##") result = crew.kickoff() print("\n\n---\n## Task Result ##\n---") print(result)

这段代码使用 CrewAI 库创建了一个 AI 代理，用于规划并撰写给定主题的摘要。它首先导入必要的库，包括 Crew.ai 和 langchain_openai，并从 .env 文件加载环境变量。代码明确定义了一个 ChatOpenAI 语言模型供代理使用。创建了一个名为 planner_writer_agent 的代理，其角色和目标明确：规划并撰写一份简洁的摘要。该代理的背景故事强调了其在规划和技术写作方面的专长。定义了一个任务，任务描述清晰地表明其首先要制定计划，然后围绕“强化学习在人工智能中的重要性”这一主题撰写摘要，并指定了预期输出的特定格式。将代理和任务组装成一个 Crew，并设置为按顺序处理它们。最后，调用 crew.kickoff() 方法来执行定义的任务，并打印结果。

This code uses the CrewAI library to create an AI agent that plans and writes a summary on a given topic. It starts by importing necessary libraries, including Crew.ai and langchain_openai, and loading environment variables from a .env file. A ChatOpenAI language model is explicitly defined for use with the agent. An Agent named planner_writer_agent is created with a specific role and goal: to plan and then write a concise summary. The agent's backstory emphasizes its expertise in planning and technical writing. A Task is defined with a clear description to first create a plan and then write a summary on the topic "The importance of Reinforcement Learning in AI", with a specific format for the expected output. A Crew is assembled with the agent and task, set to process them sequentially. Finally, the crew.kickoff() method is called to execute the defined task and the result is printed.

Google DeepResearch

Google DeepResearch

Google Gemini DeepResearch（见图 1）是一个基于代理的系统，旨在实现自主信息检索和综合。它通过一个多步骤的代理流程运行，该流程动态且迭代地查询 Google 搜索，以系统地探索复杂主题。该系统能够处理大量的网络资源，评估收集到的数据的相关性和知识缺口，并执行后续搜索以解决这些问题。最终输出将经过验证的信息整合为一个结构化的多页摘要，并附有原始来源的引用。

Google Gemini DeepResearch (see Fig.1)  is an agent-based system designed for autonomous information retrieval and synthesis. It functions through a multi-step agentic pipeline that dynamically and iteratively queries Google Search to systematically explore complex topics. The system is engineered to process a large corpus of web-based sources, evaluate the collected data for relevance and knowledge gaps, and perform subsequent searches to address them. The final output consolidates the vetted information into a structured, multi-page summary with citations to the original sources.

进一步来说，该系统的运行并非单一的查询-响应事件，而是一个受控的、长时间运行的过程。它首先将用户的提示信息分解成一个多点研究计划（见图1），然后将其呈现给用户以供审核和修改。这使得用户能够在执行研究计划之前与其协作，共同塑造研究方向。一旦计划获得批准，智能体流程便会启动其迭代式搜索和分析循环。这不仅仅是执行一系列预定义的搜索；智能体还会根据收集到的信息动态地构建和优化查询，主动识别知识空白、验证数据点并解决差异。

Expanding on this, the system's operation is not a single query-response event but a managed, long-running process. It begins by deconstructing a user's prompt into a multi-point research plan (see Fig. 1), which is then presented to the user for review and modification. This allows for a collaborative shaping of the research trajectory before execution. Once the plan is approved, the agentic pipeline initiates its iterative search-and-analysis loop. This involves more than just executing a series of predefined searches; the agent dynamically formulates and refines its queries based on the information it gathers, actively identifying knowledge gaps, corroborating data points, and resolving discrepancies.

图 1：Google Deep Research 代理生成使用 Google 搜索作为工具的执行计划。

Fig. 1: Google Deep Research agent generating an execution plan for using Google Search as a tool.

该系统架构的关键组成部分在于其异步管理流程的能力。这种设计确保了调查（可能涉及分析数百个信息源）能够抵御单点故障，并允许用户在调查完成后退出并收到通知。系统还可以整合用户提供的文档，将来自私人来源的信息与其基于网络的研究相结合。最终输出并非简单的调查结果列表，而是一份结构化的多页报告。在综合阶段，模型会对收集到的信息进行批判性评估，识别主要主题，并将内容组织成逻辑清晰、条理分明的叙述。该报告采用交互式设计，通常包含音频概述、图表以及指向原始引用来源的链接等功能，方便用户进行验证和深入探索。除了综合结果之外，模型还会明确返回其搜索和查阅的所有来源列表（见图 2）。这些来源以引文的形式呈现，提供完全透明的信息，并允许用户直接访问原始信息。整个过程将简单的查询转化为全面、综合的知识体系。

A key architectural component is the system's ability to manage this process asynchronously. This design ensures that the investigation, which can involve analyzing hundreds of sources, is resilient to single-point failures and allows the user to disengage and be notified upon completion. The system can also integrate user-provided documents, combining information from private sources with its web-based research. The final output is not merely a concatenated list of findings but a structured, multi-page report. During the synthesis phase, the model performs a critical evaluation of the collected information, identifying major themes and organizing the content into a coherent narrative with logical sections. The report is designed to be interactive, often including features like an audio overview, charts, and links to the original cited sources, allowing for verification and further exploration by the user. In addition to the synthesized results, the model explicitly returns the full list of sources it searched and consulted (see Fig.2). These are presented as citations, providing complete transparency and direct access to the primary information. This entire process transforms a simple query into a comprehensive, synthesized body of knowledge.

图 2：深度研究计划的执行示例，最终使用 Google 搜索作为工具来搜索各种网络资源。

Fig. 2: An example of Deep Research plan being executed, resulting in Google Search being used as a tool to search various web sources.

Gemini DeepResearch 通过减少手动数据采集和整合所需的大量时间和资源投入，提供了一种更结构化、更全面的信息发现方法。该系统的价值在各个领域复杂、多方面的研究任务中尤为显著。

By mitigating the substantial time and resource investment required for manual data acquisition and synthesis, Gemini DeepResearch provides a more structured and exhaustive method for information discovery. The system's value is particularly evident in complex, multi-faceted research tasks across various domains.

例如，在竞争分析中，可以指示代理系统地收集和整理市场趋势、竞争对手产品规格、来自各种在线渠道的公众舆论以及营销策略等数据。这种自动化流程取代了手动跟踪多个竞争对手的繁琐工作，使分析师能够专注于更高层次的战略解读，而不是数据收集（见图 3）。

For instance, in competitive analysis, the agent can be directed to systematically gather and collate data on market trends, competitor product specifications, public sentiment from diverse online sources, and marketing strategies. This automated process replaces the laborious task of manually tracking multiple competitors, allowing analysts to focus on higher-order strategic interpretation rather than data collection (see Fig. 3).

图 3：Google Deep Research 代理生成的最终输出，代表我们分析使用 Google 搜索作为工具获得的来源。

Fig. 3: Final output generated by the Google Deep Research agent, analyzing on our behalf sources obtained using Google Search as a tool.

同样，在学术探索中，该系统可作为开展广泛文献综述的强大工具。它可以识别和总结基础性论文，追踪概念在众多出版物中的发展历程，并绘制特定领域内新兴的研究前沿，从而加速学术探究的初始阶段，即最耗时的阶段。

Similarly, in academic exploration, the system serves as a powerful tool for conducting extensive literature reviews. It can identify and summarize foundational papers, trace the development of concepts across numerous publications, and map out emerging research fronts within a specific field, thereby accelerating the initial and most time-consuming phase of academic inquiry.

这种方法的效率源于迭代搜索和筛选循环的自动化，而这正是人工研究的核心瓶颈。系统能够在相当的时间范围内处理比人类研究人员通常能够处理的信息量更大、种类更丰富的信息源，从而实现了全面性。这种更广泛的分析范围有助于减少选择偏差的可能性，并增加发现那些不太明显但可能至关重要的信息的可能性，从而对研究主题形成更稳健、更有力的理解。

The efficiency of this approach stems from the automation of the iterative search-and-filter cycle, which is a core bottleneck in manual research. Comprehensiveness is achieved by the system's capacity to process a larger volume and variety of information sources than is typically feasible for a human researcher within a comparable timeframe. This broader scope of analysis helps to reduce the potential for selection bias and increases the likelihood of uncovering less obvious but potentially critical information, leading to a more robust and well-supported understanding of the subject matter.

OpenAI 深度研究 API

OpenAI Deep Research API

OpenAI 深度研究 API 是一款专为自动化复杂研究任务而设计的专用工具。它采用先进的智能体模型，能够独立进行推理、规划和综合来自真实世界的信息。与简单的问答模型不同，它能够接收一个高级查询，并自主地将其分解为子问题，利用其内置工具执行网络搜索，最终生成一份结构化且包含丰富引用的最终报告。该 API 提供对整个流程的直接编程访问，在撰写本文时，它使用诸如 o3-deep-research-2025-06-26 等模型进行高质量综合，以及速度更快的 o4-mini-deep-research-2025-06-26 模型来处理对延迟敏感的应用。

The OpenAI Deep Research API is a specialized tool designed to automate complex research tasks. It utilizes an advanced, agentic model that can independently reason, plan, and synthesize information from real-world sources. Unlike a simple Q&A model, it takes a high-level query and autonomously breaks it down into sub-questions, performs web searches using its built-in tools, and delivers a structured, citation-rich final report. The API provides direct programmatic access to this entire process, using  at the time of writing models like o3-deep-research-2025-06-26 for high-quality synthesis and the faster o4-mini-deep-research-2025-06-26 for latency-sensitive application

深度研究 API 的优势在于它可以自动完成原本需要耗费数小时的手动研究工作，生成专业级、数据驱动的报告，这些报告可用于指导业务战略、投资决策或政策建议。其主要优势包括：

The Deep Research API is useful because it automates what would otherwise be hours of manual research, delivering professional-grade, data-driven reports suitable for informing business strategy, investment decisions, or policy recommendations. Its key benefits include:

• 结构化、引用输出：  它生成组织良好的报告，其中包含链接到源元数据的内联引用，确保声明可验证且有数据支持。
• Structured, Cited Output:  It produces well-organized reports with inline citations linked to source metadata, ensuring claims are verifiable and data-backed.
• 透明度：  与 ChatGPT 中抽象化的流程不同，该 API 公开了所有中间步骤，包括代理的推理过程、执行的具体网络搜索查询以及运行的任何代码。这使得用户能够进行详细的调试和分析，并更深入地了解最终答案的构建方式。
• Transparency:  Unlike the abstracted process in ChatGPT, the API exposes all intermediate steps, including the agent's reasoning, the specific web search queries it executed, and any code it ran. This allows for detailed debugging, analysis, and a deeper understanding of how the final answer was constructed.
• 可扩展性：  它支持模型上下文协议 (MCP)，使开发人员能够将代理连接到私有知识库和内部数据源，将公共网络研究与专有信息融合在一起。
• Extensibility:  It supports the Model Context Protocol (MCP), enabling developers to connect the agent to private knowledge bases and internal data sources, blending public web research with proprietary information.

要使用此 API，您需要向`client.responses.create`端点 发送请求 ，并指定模型、输入提示以及代理可以使用的工具。输入通常包含一个 ` system_message`  ，用于定义代理的角色和所需的输出格式，以及 ` user_query` 。您还必须包含 ` web_search_preview`  工具，并且可以选择添加其他工具，例如用于内部数据的 `code_interpreter`  或自定义 MCP 工具（参见第 10 章）。

To use the API, you send a request to the client.responses.create  endpoint, specifying a model, an input prompt, and the tools the agent can use. The input typically includes a system_message  that defines the agent's persona and desired output format, along with the user_query . You must also include the web_search_preview  tool and can optionally add others like code_interpreter  or custom MCP tools (see Chapter 10) for internal data.

from openai import OpenAI # Initialize the client with your API key client = OpenAI(api_key="YOUR_OPENAI_API_KEY") # Define the agent's role and the user's research question system_message = """You are a professional researcher preparing a structured, data-driven report. Focus on data-rich insights, use reliable sources, and include inline citations.""" user_query = "Research the economic impact of semaglutide on global healthcare systems." # Create the Deep Research API call response = client.responses.create(  model="o3-deep-research-2025-06-26",  input=[    {      "role": "developer",      "content": [{"type": "input_text", "text": system_message}]    },    {      "role": "user",      "content": [{"type": "input_text", "text": user_query}]    }  ],  reasoning={"summary": "auto"},  tools=[{"type": "web_search_preview"}] ) # Access and print the final report from the response final_report = response.output[-1].content[0].text print(final_report) # --- ACCESS INLINE CITATIONS AND METADATA --- print("--- CITATIONS ---") annotations = response.output[-1].content[0].annotations if not annotations:    print("No annotations found in the report.") else:    for i, citation in enumerate(annotations):        # The text span the citation refers to        cited_text = final_report[citation.start_index:citation.end_index]        print(f"Citation {i+1}:")        print(f"  Cited Text: {cited_text}")        print(f"  Title: {citation.title}")        print(f"  URL: {citation.url}")        print(f"  Location: chars {citation.start_index}–{citation.end_index}") print("\n" + "="*50 + "\n") # --- INSPECT INTERMEDIATE STEPS --- print("--- INTERMEDIATE STEPS ---") # 1. Reasoning Steps: Internal plans and summaries generated by the model. try:    reasoning_step = next(item for item in response.output if item.type == "reasoning")    print("\n[Found a Reasoning Step]")    for summary_part in reasoning_step.summary:        print(f"  - {summary_part.text}") except StopIteration:    print("\nNo reasoning steps found.") # 2. Web Search Calls: The exact search queries the agent executed. try:    search_step = next(item for item in response.output if item.type == "web_search_call")    print("\n[Found a Web Search Call]")    print(f"  Query Executed: '{search_step.action['query']}'")    print(f"  Status: {search_step.status}") except StopIteration:    print("\nNo web search steps found.") # 3. Code Execution: Any code run by the agent using the code interpreter. try:    code_step = next(item for item in response.output if item.type == "code_interpreter_call")    print("\n[Found a Code Execution Step]")    print("  Code Input:")    print(f"  ```python\n{code_step.input}\n  ```")    print("  Code Output:")    print(f"  {code_step.output}") except StopIteration:    print("\nNo code execution steps found.")

这段代码片段利用 OpenAI API 执行“深度研究”任务。它首先使用您的 API 密钥初始化 OpenAI 客户端，这对于身份验证至关重要。然后，它将 AI 代理的角色定义为专业研究员，并设置用户关于司美格鲁肽经济影响的研究问题。代码构建了一个对 o3-deep-research-2025-06-26 模型的 API 调用，并将定义的系统消息和用户查询作为输入。它还请求自动生成推理摘要并启用网络搜索功能。API 调用完成后，它会提取并打印最终生成的报告。

This code snippet utilizes the OpenAI API to perform a "Deep Research" task. It starts by initializing the OpenAI client with your API key, which is crucial for authentication. Then, it defines the role of the AI agent as a professional researcher and sets the user's research question about the economic impact of semaglutide. The code constructs an API call to the o3-deep-research-2025-06-26 model, providing the defined system message and user query as input. It also requests an automatic summary of the reasoning and enables web search capabilities. After making the API call, it extracts and prints the final generated report.

随后，它会尝试访问并显示报告注释中的内联引用和元数据，包括引用的文本、标题、URL 以及在报告中的位置。最后，它会检查并打印模型执行的中间步骤的详细信息，例如推理步骤、网络搜索调用（包括执行的查询）以及如果使用了代码解释器，则还会打印任何代码执行步骤。

Subsequently, it attempts to access and display inline citations and metadata from the report's annotations, including the cited text, title, URL, and location within the report. Finally, it inspects and prints details about the intermediate steps the model took, such as reasoning steps, web search calls (including the query executed), and any code execution steps if a code interpreter was used.

概览

At a Glance

问题： 复杂问题往往无法通过单一行动解决，需要远见卓识才能达成预期结果。缺乏结构化的方法，智能体系统难以处理涉及多个步骤和依赖关系的复杂请求。这使得将高层目标分解为一系列易于管理的、可执行的小任务变得困难。因此，系统无法有效制定策略，导致在面对复杂目标时出现不完整或错误的结果。 

What:   Complex problems often cannot be solved with a single action and require foresight to achieve a desired outcome. Without a structured approach, an agentic system struggles to handle multifaceted requests that involve multiple steps and dependencies. This makes it difficult to break down high-level objectives into a manageable series of smaller, executable tasks. Consequently, the system fails to strategize effectively, leading to incomplete or incorrect results when faced with intricate goals.

原因： 规划模式提供了一种标准化的解决方案，它首先让智能体系统创建一个连贯的计划来实现目标。该模式将高层目标分解为一系列更小的、可执行的步骤或子目标。这使得系统能够管理复杂的工作流程，协调各种工具，并以逻辑顺序处理依赖关系。LLM（生命周期管理）尤其适合这种模式，因为它们可以基于庞大的训练数据生成合理有效的计划。这种结构化的方法将简单的被动式智能体转变为能够主动实现复杂目标，甚至在必要时调整计划的战略执行者。 

Why:   The Planning pattern offers a standardized solution by having an agentic system first create a coherent plan to address a goal. It involves decomposing a high-level objective into a sequence of smaller, actionable steps or sub-goals. This allows the system to manage complex workflows, orchestrate various tools, and handle dependencies in a logical order. LLMs are particularly well-suited for this, as they can generate plausible and effective plans based on their vast training data. This structured approach transforms a simple reactive agent into a strategic executor that can proactively work towards a complex objective and even adapt its plan if necessary.

经验法则： 当用户请求过于复杂，无法通过单个操作或工具处理时，请使用此模式。它非常适合自动化多步骤流程，例如生成详细的研究报告、新员工入职培训或执行竞品分析。当任务需要一系列相互依赖的操作才能得出最终的综合结果时，请应用规划模式。

Rule of thumb: Use this pattern when a user's request is too complex to be handled by a single action or tool. It is ideal for automating multi-step processes, such as generating a detailed research report, onboarding a new employee, or executing a competitive analysis. Apply the Planning pattern whenever a task requires a sequence of interdependent operations to reach a final, synthesized outcome.

可视化摘要

Visual summary

图 4 ；  规划设计模式

Fig.4 ;  Planning design pattern

要点总结

Key Takeaways

• 规划使代理人能够将复杂的目标分解为可操作的、循序渐进的步骤。
• Planning enables agents to break down complex goals into actionable, sequential steps.
• 它对于处理多步骤任务、工作流程自动化和驾驭复杂环境至关重要。
• It is essential for handling multi-step tasks, workflow automation, and navigating complex environments.
• L LM  可以根据任务描述生成逐步方法来进行规划。
• L LMs  can perform planning by generating step-by-step approaches based on task descriptions.
• 在代理框架中，明确提示或设计需要规划步骤的任务可以鼓励这种行为。
• Explicitly prompting or designing tasks to require planning steps encourages this behavior in agent frameworks.
• Google Deep Research 是一个代理，它代表我们分析使用 Google 搜索获取的信息。  它负责思考、规划和执行。
• Google Deep Research is an agent analyzing on our behalf sources obtained using Google Search as a tool.  It reflects, plans, and executes

结论

Conclusion

总之，规划模式是提升智能体系统的基础组件，它将智能体系统从简单的被动响应者提升为具有战略性和目标导向的执行者。现代大型语言模型为此提供了核心能力，能够自主地将高层目标分解为连贯且可操作的步骤。这种模式的适用范围很广，从简单的顺序任务执行（例如 CrewAI 智能体创建并执行写作计划）到更复杂、更动态的系统。Google DeepResearch 智能体便是这种高级应用的典范，它能够创建迭代式研究计划，并根据持续的信息收集进行调整和演进。最终，规划模式为解决复杂问题提供了连接人类意图和自动化执行的关键桥梁。通过构建问题解决方法，这种模式使智能体能够管理复杂的工作流程，并提供全面、综合的结果。

In conclusion, the Planning pattern is a foundational component that elevates agentic systems from simple reactive responders to strategic, goal-oriented executors. Modern large language models provide the core capability for this, autonomously decomposing high-level objectives into coherent, actionable steps. This pattern scales from straightforward, sequential task execution, as demonstrated by the CrewAI agent creating and following a writing plan, to more complex and dynamic systems. The Google DeepResearch agent exemplifies this advanced application, creating iterative research plans that adapt and evolve based on continuous information gathering. Ultimately, planning provides the essential bridge between human intent and automated execution for complex problems. By structuring a problem-solving approach, this pattern enables agents to manage intricate workflows and deliver comprehensive, synthesized results.

参考

References

1. Google DeepResearch（Gemini 特辑）： gemini.google.com  
2. Google DeepResearch (Gemini Feature): gemini.google.com  
3. OpenAI，《深度研究简介》   https://openai.com/index/introducing-deep-research/  
4. OpenAI ,Introducing deep research   https://openai.com/index/introducing-deep-research/  
5. Perplexity，《Perplexity深度研究简介》， https://www.perplexity.ai/hub/blog/introducing-perplexity-deep-research  
6. Perplexity, Introducing Perplexity Deep Research, https://www.perplexity.ai/hub/blog/introducing-perplexity-deep-research  

第七章：多智能体协作

Chapter 7: Multi-Agent Collaboration

虽然单体智能体架构对于定义明确的问题可能有效，但面对复杂的多领域任务时，其能力往往会受到限制。多智能体协作模式通过将系统构建为由多个功能各异、专业化的智能体组成的协作集合来解决这些局限性。这种方法基于任务分解的原则，即将一个高层目标分解为若干离散的子问题。然后，将每个子问题分配给一个拥有最适合该任务的特定工具、数据访问或推理能力的智能体。

While a monolithic agent architecture can be effective for well-defined problems, its capabilities are often constrained when faced with complex, multi-domain tasks. The Multi-Agent Collaboration pattern addresses these limitations by structuring a system as a cooperative ensemble of distinct, specialized agents. This approach is predicated on the principle of task decomposition, where a high-level objective is broken down into discrete sub-problems. Each sub-problem is then assigned to an agent possessing the specific tools, data access, or reasoning capabilities best suited for that task.

例如，一个复杂的研究查询可以被分解，并分配给不同的代理：研究代理负责信息检索，数据分析代理负责统计处理，综合代理负责生成最终报告。这种系统的有效性不仅取决于分工，更关键地依赖于代理间通信机制。这需要标准化的通信协议和共享本体，使代理能够交换数据、分配子任务并协调行动，从而确保最终输出的一致性。

For example, a complex research query might be decomposed and assigned to a Research Agent for information retrieval, a Data Analysis Agent for statistical processing, and a Synthesis Agent for generating the final report. The efficacy of such a system is not merely due to the division of labor but is critically dependent on the mechanisms for inter-agent communication. This requires a standardized communication protocol and a shared ontology, allowing agents to exchange data, delegate sub-tasks, and coordinate their actions to ensure the final output is coherent.

这种分布式架构具有多项优势，包括增强的模块化、可扩展性和鲁棒性，因为单个智能体的故障并不一定会导致整个系统崩溃。这种协作方式能够产生协同效应，使得多智能体系统的集体性能超越了其中任何单个智能体的潜在能力。

This distributed architecture offers several advantages, including enhanced modularity, scalability, and robustness, as the failure of a single agent does not necessarily cause a total system failure. The collaboration allows for a synergistic outcome where the collective performance of the multi-agent system surpasses the potential capabilities of any single agent within the ensemble.

多智能体协作模式概述

Multi-Agent Collaboration Pattern Overview

多智能体协作模式是指设计多个独立或半独立的智能体协同工作以实现共同目标的系统。每个智能体通常都有明确的角色、与总体目标相一致的具体目标，并且可能拥有不同的工具或知识库访问权限。这种模式的优势在于智能体之间的交互和协同作用。

The Multi-Agent Collaboration pattern involves designing systems where multiple independent or semi-independent agents work together to achieve a common goal. Each agent typically has a defined role, specific goals aligned with the overall objective, and potentially access to different tools or knowledge bases. The power of this pattern lies in the interaction and synergy between these agents.

合作可以采取多种形式：

Collaboration can take various forms:

• 顺序交接：  一个代理完成一项任务，并将其输出传递给另一个代理，以执行管道中的下一步（类似于规划模式，但明确涉及不同的代理）。
• Sequential Handoffs:  One agent completes a task and passes its output to another agent for the next step in a pipeline (similar to the Planning pattern, but explicitly involving different agents).
• 并行处理：  多个智能体同时处理问题的不同部分，然后将它们的结果合并起来。
• Parallel Processing:  Multiple agents work on different parts of a problem simultaneously, and their results are later combined.
• 辩论与共识： 多智能体协作 ，其中 具有不同视角和信息来源的智能体参与讨论以评估各种方案，最终达成共识或做出更明智的决定。 
• Debate and Consensus:   Multi-Agent Collaboration  where  Agents with varied perspectives and information sources engage in discussions to evaluate options, ultimately reaching a consensus or a more informed decision.
• 层级结构：  管理代理可以 根据工作代理的工具访问权限或插件功能动态地将任务委派给它们，并综合分析结果。每个代理还可以处理相关的工具组，而不是由单个代理处理所有工具。 
• Hierarchical Structures:  A manager agent might delegate tasks to worker agents dynamically   based on their tool access or plugin capabilities and synthesize their results. Each agent can also handle relevant groups of tools, rather than a single agent handling all the tools.
• 专家团队：  在不同领域拥有专业知识的代理人（例如，研究员、作家、编辑）合作，共同产出复杂的成果。
• Expert Teams:  Agents with specialized knowledge in different domains (e.g., a researcher, a writer, an editor) collaborate to produce a complex output.

• 评审员模式： 智能体创建初始输出，例如计划、草稿或答案。 第二组智能体随后对这些输出进行严格评估，检查其是否符合政策、安全性、合规性、正确性、质量以及与组织目标的契合度。原始创建者或最终智能体根据反馈修改输出。这种模式在代码生成、研究论文写作、逻辑检查和确保伦理一致性方面尤为有效。该方法的优势包括更高的鲁棒性、更优的质量以及更低的出现幻觉或错误的可能性。       

• Critic-Reviewer: Agents create initial outputs such as plans, drafts, or answers.   A second group of agents then critically assesses this output for adherence to policies, security, compliance, correctness, quality, and alignment with organizational objectives.   The original creator or a final agent revises the output based on this feedback.   This pattern is particularly effective for code generation, research writing, logic checking, and ensuring ethical alignment.   The advantages of this approach include increased robustness, improved quality, and a reduced likelihood of hallucinations or errors.

多智能体系统（见图 1）从根本上包括：划分智能体的角色和职责，建立智能体之间交换信息的通信渠道，以及制定指导其协作努力的任务流程或交互协议。

A multi-agent system (see Fig.1) fundamentally comprises the delineation of agent roles and responsibilities, the establishment of communication channels through which agents exchange information, and the formulation of a task flow or interaction protocol that directs their collaborative endeavors.

图1：多智能体系统示例

Fig.1: Example of multi-agent system

Crew AI 和 Google ADK 等框架旨在通过提供用于定义代理、任务及其交互过程的结构来促进这种范式。 这种方法对于需要各种专业知识、包含多个离散阶段或利用并发处理优势以及跨代理信息验证的挑战尤为有效。 

Frameworks such as Crew AI and Google ADK are engineered to facilitate this paradigm by providing structures for the specification of agents, tasks, and their interactive procedures.   This approach is particularly effective for challenges necessitating a variety of specialized knowledge, encompassing multiple discrete phases, or leveraging the advantages of concurrent processing and the corroboration of information across agents.

实际应用及案例

Practical Applications & Use Cases

多智能体协作是一种强大的模式，可应用于众多领域：

Multi-Agent Collaboration is a powerful pattern applicable across numerous domains:

• 复杂研究与分析：  一个由多个智能体组成的团队可以协作开展研究项目。一个智能体可能专门负责搜索学术数据库，另一个负责总结研究结果，第三个负责识别趋势，第四个负责将信息综合成报告。这与人类研究团队的运作方式类似。
• Complex Research and Analysis:  A team of agents could collaborate on a research project. One agent might specialize in searching academic databases, another in summarizing findings, a third in identifying trends, and a fourth in synthesizing the information into a report. This mirrors how a human research team might operate.
• 软件开发：  想象一下，多个智能体协同工作来构建软件。一个智能体可以是需求分析师，另一个可以是代码生成器，第三个可以是测试人员，第四个可以是文档编写者。他们可以相互传递输出，以构建和验证组件。
• Software Development:  Imagine agents collaborating on building software. One agent could be a requirements analyst, another a code generator, a third a tester, and a fourth a documentation writer. They could pass outputs between each other to build and verify components.
• 创意内容生成：  创建营销活动可能需要市场调研员、文案撰写员、平面设计员（使用图像生成工具）和社交媒体日程安排员共同协作。
• Creative Content Generation:  Creating a marketing campaign could involve a market research agent, a copywriter agent, a graphic design agent (using image generation tools), and a social media scheduling agent, all working together.
• 金融分析：  多智能体系统可以分析金融市场。各个智能体可以分别专注于获取股票数据、分析新闻情绪、进行技术分析以及生成投资建议。
• Financial Analysis:  A multi-agent system could analyze financial markets. Agents might specialize in fetching stock data, analyzing news sentiment, performing technical analysis, and generating investment recommendations.
• 客户支持升级： 一线支持人员可以处理初始查询，并在需要时将复杂问题升级给专家（例如技术专家或计费专家），从而根据问题的复杂性进行顺序交接。 
• Customer Support Escalation:   A front-line support agent could handle initial queries, escalating complex issues to a specialist agent (e.g., a technical expert or a billing specialist) when needed, demonstrating a sequential handoff based on problem complexity.
• 供应链优化：  代理可以代表供应链中的不同节点（供应商、制造商、分销商），并协作优化库存水平、物流和调度，以应对不断变化的需求或中断。
• Supply Chain Optimization:  Agents could represent different nodes in a supply chain (suppliers, manufacturers, distributors) and collaborate to optimize inventory levels, logistics, and scheduling in response to changing demand or disruptions.
• 网络分析与修复 ： 自主运行从智能体架构中获益匪浅，尤其是在故障定位方面。 多个智能体可以协作对问题进行分类和修复，并提出最佳解决方案。这些智能体还可以与传统的机器学习模型和工具集成，在利用现有系统的同时，提供生成式人工智能的优势。   
• Network Analysis & Remediation : Autonomous operations benefit greatly from an agentic architecture, particularly in failure pinpointing.   Multiple agents can collaborate to triage and remediate issues, suggesting optimal actions.   These agents can also integrate with traditional machine learning models and tooling, leveraging existing systems while simultaneously offering the advantages of Generative AI.

通过划分专门的代理并精心协调它们之间的相互关系，开发人员能够构建具有增强的模块化、可扩展性和解决复杂问题能力的系统，而这些问题对于单个集成代理来说是无法克服的。  

The capacity to delineate specialized agents and meticulously orchestrate their interrelationships empowers developers to construct systems exhibiting enhanced modularity, scalability, and the ability to address complexities that would prove insurmountable for a singular, integrated agent.  

多智能体协作：探索相互关系和沟通结构

Multi-Agent Collaboration: Exploring Interrelationships and Communication Structures

理解智能体之间复杂的交互和通信方式是设计高效多智能体系统的基础。 如图 2 所示，存在一系列相互关系和通信模型，从最简单的单智能体场景到复杂的定制化协作框架。每种模型都具有独特的优势和挑战，影响着多智能体系统的整体效率、鲁棒性和适应性。   

Understanding the intricate ways in which agents interact and communicate is fundamental to designing effective multi-agent systems.   As depicted in Fig. 2, a spectrum of interrelationship and communication models exists, ranging from the simplest single-agent scenario to complex, custom-designed collaborative frameworks.   Each model presents unique advantages and challenges, influencing the overall efficiency, robustness, and adaptability of the multi-agent system.

1. 单智能体： 最基本的“单智能体”是指无需与其他实体直接交互或通信即可自主运行的智能体。虽然这种模型易于实现和管理，但其能力本质上受限于单个智能体的范围和资源。它适用于可分解为独立子问题的任务，每个子问题都可以由单个自给自足的智能体解决。     

1.   Single Agent:  At the most basic level, a "Single Agent" operates autonomously without direct interaction or communication with other entities.   While this model is straightforward to implement and manage, its capabilities are inherently limited by the individual agent's scope and resources.   It is suitable for tasks that are decomposable into independent sub-problems, each solvable by a single, self-sufficient agent.

2. 网络模型： “网络”模型代表着协作方面的重要一步，其中多个主体以去中心化的方式直接相互交互。通信通常以点对点方式进行，从而实现信息、资源乃至任务的共享。该模型增强了系统的韧性，因为单个主体的故障并不一定会瘫痪整个系统。然而，在大型、非结构化的网络中管理通信开销并确保决策的一致性可能极具挑战性。       

2.   Network:  The "Network" model represents a significant step towards collaboration, where multiple agents interact directly with each other in a decentralized fashion.   Communication typically occurs peer-to-peer, allowing for the sharing of information, resources, and even tasks.   This model fosters resilience, as the failure of one agent does not necessarily cripple the entire system.   However, managing communication overhead and ensuring coherent decision-making in a large, unstructured network can be challenging.

3. 主管： 在“主管”模式下，一名专门的代理人（即“主管”）负责监督和协调一组下属代理人的活动。主管充当沟通、任务分配和冲突解决的中心枢纽。这种层级结构提供了清晰的职权范围，可以简化管理和控制。然而，它也引入了一个单点故障（主管），如果主管被大量下属或复杂任务压得喘不过气来，就可能成为瓶颈。       

3.   Supervisor:  In the "Supervisor" model, a dedicated agent, the "supervisor," oversees and coordinates the activities of a group of subordinate agents.   The supervisor acts as a central hub for communication, task allocation, and conflict resolution.   This hierarchical structure offers clear lines of authority and can simplify management and control.   However, it introduces a single point of failure (the supervisor) and can become a bottleneck if the supervisor is overwhelmed by a large number of subordinates or complex tasks.

4. 监督者作为工具： 该模型是对“监督者”概念的细致延伸。监督者的角色不再是直接的命令和控制，而是更多地为其他主体提供资源、指导或分析支持。监督者可以提供工具、数据或计算服务，帮助其他主体更高效地完成任务，而无需事无巨细地干预它们的每一个行动。这种方法旨在充分利用监督者的能力，同时避免实施僵化的自上而下控制。     

4.   Supervisor as a Tool:  This model is a nuanced extension of the "Supervisor" concept, where the supervisor's role is less about direct command and control and more about providing resources, guidance, or analytical support to other agents.   The supervisor might offer tools, data, or computational services that enable other agents to perform their tasks more effectively, without necessarily dictating their every action.   This approach aims to leverage the supervisor's capabilities without imposing rigid top-down control.

5. 层级式： 层级式模型扩展了主管的概念，创建了一个多层级的组织结构。这种结构包含多个层级的主管，上级主管监督下级主管，最底层则由一系列运营人员组成。这种结构非常适合处理可以分解为子问题的复杂问题，每个子问题都由层级结构中的特定层级进行管理。它为可扩展性和复杂性管理提供了一种结构化的方法，允许在既定的边界内进行分布式决策。       

5.   Hierarchical:  The "Hierarchical" model expands upon the supervisor concept to create a multi-layered organizational structure.   This involves multiple levels of supervisors, with higher-level supervisors overseeing lower-level ones, and ultimately, a collection of operational agents at the lowest tier.   This structure is well-suited for complex problems that can be decomposed into sub-problems, each managed by a specific layer of the hierarchy.   It provides a structured approach to scalability and complexity management, allowing for distributed decision-making within defined boundaries.

图 2： 智能体以各种方式进行交流和互动。

Fig. 2: Agents communicate and interact in various ways.

6. 定制模型： “定制”模型代表了多智能体系统设计中极致的灵活性。它允许创建独特的相互关系和通信结构，这些结构能够精准地满足特定问题或应用的具体需求。这可能涉及混合方法，即结合前述模型中的元素；也可能涉及从环境的独特约束和机遇中涌现出的全新设计。定制模型通常源于优化特定性能指标、处理高度动态环境或将领域特定知识融入系统架构的需求。设计和实现定制模型通常需要对多智能体系统原理有深入的理解，并仔细考虑通信协议、协调机制和涌现行为。         

6.   Custom:  The "Custom" model represents the ultimate flexibility in multi-agent system design.   It allows for the creation of unique interrelationship and communication structures tailored precisely to the specific requirements of a given problem or application.   This can involve hybrid approaches that combine elements from the previously mentioned models, or entirely novel designs that emerge from the unique constraints and opportunities of the environment.   Custom models often arise from the need to optimize for specific performance metrics, handle highly dynamic environments, or incorporate domain-specific knowledge into the system's architecture.   Designing and implementing custom models typically requires a deep understanding of multi-agent systems principles and careful consideration of communication protocols, coordination mechanisms, and emergent behaviors.

总之，对于多智能体系统而言，选择合适的相互关系和通信模型是一项至关重要的设计决策。 每种模型都有其独特的优缺点，而最优选择取决于诸多因素，例如任务的复杂性、智能体的数量、所需的自主程度、鲁棒性要求以及可接受的通信开销。未来多智能体系统的发展很可能将继续探索和完善这些模型，并开发出新的协作智能范式。   

In summary, the choice of interrelationship and communication model for a multi-agent system is a critical design decision.   Each model offers distinct advantages and disadvantages, and the optimal choice depends on factors such as the complexity of the task, the number of agents, the desired level of autonomy, the need for robustness, and the acceptable communication overhead.   Future advancements in multi-agent systems will likely continue to explore and refine these models, as well as develop new paradigms for collaborative intelligence.

动手编写代码（船员人工智能）

Hands-On code (Crew AI)

这段 Python 代码使用 CrewAI 框架定义了一个由人工智能驱动的团队，用于生成一篇关于人工智能趋势的博客文章。它首先设置环境，并从 .env 文件加载 API 密钥。应用程序的核心在于定义两个代理：一个研究员，负责查找和总结人工智能趋势；以及一个撰稿人，负责根据研究成果撰写博客文章。

This Python code defines an AI-powered crew using the CrewAI framework to generate a blog post about AI trends. It starts by setting up the environment, loading API keys from a .env file. The core of the application involves defining two agents: a researcher to find and summarize AI trends, and a writer to create a blog post based on the research.

据此定义了两个任务：一个用于研究趋势，另一个用于撰写博客文章，其中撰写任务取决于研究任务的输出。这些代理和任务随后被组装成一个“团队”（Crew），该团队定义了一个顺序流程，其中任务按顺序执行。团队使用代理、任务和一个语言模型（具体来说是“gemini-2.0-flash”模型）进行初始化。主函数使用 `kickoff()` 方法启动该团队，协调代理之间的协作以生成所需的输出。最后，代码打印团队执行的最终结果，即生成的博客文章。

Two tasks are defined accordingly: one for researching the trends and another for writing the blog post, with the writing task depending on the output of the research task. These agents and tasks are then assembled into a Crew, specifying a sequential process where tasks are executed in order. The Crew is initialized with the agents, tasks, and a language model (specifically the "gemini-2.0-flash" model). The main function executes this crew using the kickoff() method, orchestrating the collaboration between the agents to produce the desired output. Finally, the code prints the final result of the crew's execution, which is the generated blog post.

import os from dotenv import load_dotenv from crewai import Agent, Task, Crew, Process from langchain_google_genai import ChatGoogleGenerativeAI def setup_environment():    """Loads environment variables and checks for the required API key."""    load_dotenv()    if not os.getenv("GOOGLE_API_KEY"):        raise ValueError("GOOGLE_API_KEY not found. Please set it in your .env file.") def main():    """    Initializes and runs the AI crew for content creation using the latest Gemini model.    """    setup_environment()    # Define the language model to use.    # Updated to a model from the Gemini 2.0 series for better performance and features.    # For cutting-edge (preview) capabilities, you could use "gemini-2.5-flash".    llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash")    # Define Agents with specific roles and goals    researcher = Agent(        role='Senior Research Analyst',        goal='Find and summarize the latest trends in AI.',        backstory="You are an experienced research analyst with a knack for identifying key trends and synthesizing information.",        verbose=True,        allow_delegation=False,    )    writer = Agent(        role='Technical Content Writer',        goal='Write a clear and engaging blog post based on research findings.',        backstory="You are a skilled writer who can translate complex technical topics into accessible content.",        verbose=True,        allow_delegation=False,    )    # Define Tasks for the agents    research_task = Task(        description="Research the top 3 emerging trends in Artificial Intelligence in 2024-2025. Focus on practical applications and potential impact.",        expected_output="A detailed summary of the top 3 AI trends, including key points and sources.",        agent=researcher,    )    writing_task = Task(        description="Write a 500-word blog post based on the research findings. The post should be engaging and easy for a general audience to understand.",        expected_output="A complete 500-word blog post about the latest AI trends.",        agent=writer,        context=[research_task],    )    # Create the Crew    blog_creation_crew = Crew(        agents=[researcher, writer],        tasks=[research_task, writing_task],        process=Process.sequential,        llm=llm,        verbose=2 # Set verbosity for detailed crew execution logs    )    # Execute the Crew    print("## Running the blog creation crew with Gemini 2.0 Flash... ##")    try:        result = blog_creation_crew.kickoff()        print("\n------------------\n")        print("## Crew Final Output ##")        print(result)    except Exception as e:        print(f"\nAn unexpected error occurred: {e}") if __name__ == "__main__":    main()

接下来，我们将深入探讨 Google ADK 框架中的更多示例，特别强调分层、并行和顺序协调范式，以及将代理作为操作工具的实现。

We will now delve into further examples within the Google ADK framework, with particular emphasis on hierarchical, parallel, and sequential coordination paradigms, alongside the implementation of an agent as an operational instrument.

动手实践代码（Google ADK）

Hands-on Code (Google ADK)

以下代码示例演示了如何在 Google ADK 中通过创建父子关系来构建层级式代理结构。  代码定义了两种类型的代理：LlmAgent 和派生自 BaseAgent 的自定义 TaskExecutor 代理。TaskExecutor 专为特定的非 LLM 任务而设计，在本例中，它仅产生一个“任务成功完成”事件。名为 greeter 的 LlmAgent 使用指定的模型和指令进行初始化，使其充当友好的问候者。自定义 TaskExecutor 被实例化为 task_doer。创建了一个名为 coordinator 的父级 LlmAgent，同样也为其指定了模型和指令。coordinator 的指令指导其将问候委托给 greeter，将任务执行委托给 task_doer。greeter 和 task_doer 作为子代理添加到 coordinator，从而建立父子关系。代码随后断言此关系已正确设置。最后，它打印一条消息，表明代理层级结构已成功创建。

The following code example demonstrates the establishment of a hierarchical agent structure within the Google ADK through the creation of a parent-child relationship.  The code defines two types of agents: LlmAgent and a custom TaskExecutor agent derived from BaseAgent. The TaskExecutor is designed for specific, non-LLM tasks and in this example, it simply yields a "Task finished successfully" event. An LlmAgent named greeter is initialized with a specified model and instruction to act as a friendly greeter. The custom TaskExecutor is instantiated as task_doer. A parent LlmAgent called coordinator is created, also with a model and instructions. The coordinator's instructions guide it to delegate greetings to the greeter and task execution to the task_doer. The greeter and task_doer are added as sub-agents to the coordinator, establishing a parent-child relationship. The code then asserts that this relationship is correctly set up. Finally, it prints a message indicating that the agent hierarchy has been successfully created.

from google.adk.agents import LlmAgent, BaseAgent from google.adk.agents.invocation_context import InvocationContext from google.adk.events import Event from typing import AsyncGenerator # Correctly implement a custom agent by extending BaseAgent class TaskExecutor(BaseAgent):    """A specialized agent with custom, non-LLM behavior."""    name: str = "TaskExecutor"    description: str = "Executes a predefined task."    async def _run_async_impl(self, context: InvocationContext) -> AsyncGenerator[Event, None]:        """Custom implementation logic for the task."""        # This is where your custom logic would go.        # For this example, we'll just yield a simple event.        yield Event(author=self.name, content="Task finished successfully.") # Define individual agents with proper initialization # LlmAgent requires a model to be specified. greeter = LlmAgent(    name="Greeter",    model="gemini-2.0-flash-exp",    instruction="You are a friendly greeter." ) task_doer = TaskExecutor() # Instantiate our concrete custom agent # Create a parent agent and assign its sub-agents # The parent agent's description and instructions should guide its delegation logic. coordinator = LlmAgent(    name="Coordinator",    model="gemini-2.0-flash-exp",    description="A coordinator that can greet users and execute tasks.",    instruction="When asked to greet, delegate to the Greeter. When asked to perform a task, delegate to the TaskExecutor.",    sub_agents=[        greeter,        task_doer    ] ) # The ADK framework automatically establishes the parent-child relationships. # These assertions will pass if checked after initialization. assert greeter.parent_agent == coordinator assert task_doer.parent_agent == coordinator print("Agent hierarchy created successfully.")

这段代码示例展示了如何在 Google ADK 框架中使用 LoopAgent 来构建迭代工作流。  代码定义了两个代理：ConditionChecker 和 ProcessingStep。ConditionChecker 是一个自定义代理，用于检查会话状态中的“status”值。如果“status”值为“completed”，ConditionChecker 会触发一个事件来停止循环。否则，它会触发一个事件来继续循环。ProcessingStep 是一个使用“gemini-2.0-flash-exp”模型的 LlmAgent。它的指令是执行一项任务，如果是最后一步，则将会话的“status”值设置为“completed”。此外，还创建了一个名为 StatusPoller 的 LoopAgent。StatusPoller 的 max_iterations 设置为 10。StatusPoller 包含 ProcessingStep 和 ConditionChecker 的一个实例作为子代理。LoopAgent 将按顺序执行这些子代理，最多执行 10 次迭代，如果 ConditionChecker 检测到状态为“completed”，则停止执行。

This code excerpt illustrates the employment of the LoopAgent within the Google ADK framework to establish iterative workflows.  The code defines two agents: ConditionChecker and ProcessingStep. ConditionChecker is a custom agent that checks a "status" value in the session state. If the "status" is "completed", ConditionChecker escalates an event to stop the loop. Otherwise, it yields an event to continue the loop. ProcessingStep is an LlmAgent using the "gemini-2.0-flash-exp" model. Its instruction is to perform a task and set the session "status" to "completed" if it's the final step. A LoopAgent named StatusPoller is created. StatusPoller is configured with max_iterations=10. StatusPoller includes both ProcessingStep and an instance of ConditionChecker as sub-agents. The LoopAgent will execute the sub-agents sequentially for up to 10 iterations, stopping if ConditionChecker finds the status is "completed".

i mport asyncio from typing import AsyncGenerator from google.adk.agents import LoopAgent, LlmAgent, BaseAgent from google.adk.events import Event, EventActions from google.adk.agents.invocation_context import InvocationContext # Best Practice: Define custom agents as complete, self-describing classes. class ConditionChecker(BaseAgent):    """A custom agent that checks for a 'completed' status in the session state."""    name: str = "ConditionChecker"    description: str = "Checks if a process is complete and signals the loop to stop."    async def _run_async_impl(        self, context: InvocationContext    ) -> AsyncGenerator[Event, None]:        """Checks state and yields an event to either continue or stop the loop."""        status = context.session.state.get("status", "pending")        is_done = (status == "completed")        if is_done:            # Escalate to terminate the loop when the condition is met.            yield Event(author=self.name, actions=EventActions(escalate=True))        else:            # Yield a simple event to continue the loop.            yield Event(author=self.name, content="Condition not met, continuing loop.") # Correction: The LlmAgent must have a model and clear instructions. process_step = LlmAgent(    name="ProcessingStep",    model="gemini-2.0-flash-exp",    instruction="You are a step in a longer process. Perform your task. If you are the final step, update session state by setting 'status' to 'completed'." ) # The LoopAgent orchestrates the workflow. poller = LoopAgent(    name="StatusPoller",    max_iterations=10,    sub_agents=[        process_step,        ConditionChecker() # Instantiating the well-defined custom agent.    ] ) # This poller will now execute 'process_step' # and then 'ConditionChecker' # repeatedly until the status is 'completed' or 10 iterations # have passed.

这段代码示例 阐述了 Google ADK 中的 SequentialAgent 模式  ，该模式专为构建线性工作流而设计。  这段代码使用 google.adk.agents 库定义了一个顺序代理管道。该管道包含两个代理：step1 和 step2。step1 名为“Step1_Fetch”，其输出将存储在会话状态中，键名为“data”。step2 名为“Step2_Process”，其指令是分析存储在 session.state["data"] 中的信息并提供摘要。名为“MyPipeline”的 SequentialAgent 负责协调这些子代理的执行。当管道运行并传入初始输入时，step1 将首先执行。step1 的响应将保存到会话状态中，键名为“data”。随后，step2 将执行，并根据 step1 的指令使用其存储在状态中的信息。这种结构允许构建工作流，其中一个代理的输出将成为下一个代理的输入。这是创建多步骤 AI 或数据处理管道的常见模式。

This code excerpt elucidates the SequentialAgent pattern  within the Google ADK, engineered for the construction of linear workflows.  This code defines a sequential agent pipeline using the google.adk.agents library. The pipeline consists of two agents, step1 and step2. step1 is named "Step1_Fetch" and its output will be stored in the session state under the key "data". step2 is named "Step2_Process" and is instructed to analyze the information stored in session.state["data"] and provide a summary. The SequentialAgent named "MyPipeline" orchestrates the execution of these sub-agents. When the pipeline is run with an initial input, step1 will execute first. The response from step1 will be saved into the session state under the key "data". Subsequently, step2 will execute, utilizing the information that step1 placed into the state as per its instruction. This structure allows for building workflows where the output of one agent becomes the input for the next. This is a common pattern in creating multi-step AI or data processing pipelines.

from google.adk.agents import SequentialAgent, Agent # This agent's output will be saved to session.state["data"] step1 = Agent(name="Step1_Fetch", output_key="data") # This agent will use the data from the previous step. # We instruct it on how to find and use this data. step2 = Agent(    name="Step2_Process",    instruction="Analyze the information found in state['data'] and provide a summary." ) pipeline = SequentialAgent(    name="MyPipeline",    sub_agents=[step1, step2] ) # When the pipeline is run with an initial input, Step1 will execute, # its response will be stored in session.state["data"], and then # Step2 will execute, using the information from the state as instructed.

以下代码示例展示了 Google ADK 中的 ParallelAgent 模式，该模式支持多个代理任务的并发执行。data_gatherer  被设计为同时运行两个子代理：weather_fetcher 和 news_fetcher。weather_fetcher 代理负责获取指定位置的天气数据，并将结果存储在 session.state["weather_data"] 中。类似地，news_fetcher 代理负责检索指定主题的头条新闻，并将其存储在 session.state["news_data"] 中。每个子代理都配置为使用“gemini-2.0-flash-exp”模型。ParallelAgent 负责协调这些子代理的执行，使它们能够并行工作。weather_fetcher 和 news_fetcher 的结果都会被收集并存储在 session 状态中。最后，该示例展示了如何在代理执行完成后，从 final_state 中访问已收集的​​天气和新闻数据。

The following code example illustrates the ParallelAgent pattern within the Google ADK, which facilitates the concurrent execution of multiple agent tasks.  The data_gatherer is designed to run two sub-agents concurrently: weather_fetcher and news_fetcher. The weather_fetcher agent is instructed to get the weather for a given location and store the result in session.state["weather_data"]. Similarly, the news_fetcher agent is instructed to retrieve the top news story for a given topic and store it in session.state["news_data"]. Each sub-agent is configured to use the "gemini-2.0-flash-exp" model. The ParallelAgent orchestrates the execution of these sub-agents, allowing them to work in parallel. The results from both weather_fetcher and news_fetcher would be gathered and stored in the session state. Finally, the example shows how to access the collected weather and news data from the final_state after the agent's execution is complete.

from google.adk.agents import Agent, ParallelAgent # It's better to define the fetching logic as tools for the agents # For simplicity in this example, we'll embed the logic in the agent's instruction. # In a real-world scenario, you would use tools. # Define the individual agents that will run in parallel weather_fetcher = Agent(    name="weather_fetcher",    model="gemini-2.0-flash-exp",    instruction="Fetch the weather for the given location and return only the weather report.",    output_key="weather_data"  # The result will be stored in session.state["weather_data"] ) news_fetcher = Agent(    name="news_fetcher",    model="gemini-2.0-flash-exp",    instruction="Fetch the top news story for the given topic and return only that story.",    output_key="news_data"      # The result will be stored in session.state["news_data"] ) # Create the ParallelAgent to orchestrate the sub-agents data_gatherer = ParallelAgent(    name="data_gatherer",    sub_agents=[        weather_fetcher,        news_fetcher    ] )

提供的代码片段展示了 Google ADK 中的“代理即工具”范式，它允许一个代理以类似于函数调用的方式利用另一个代理的功能。 具体来说，该代码使用 Google 的 LlmAgent 和 AgentTool 类定义了一个图像生成系统。该系统由两个代理组成：父代理 artist_agent 和子代理 image_generator_agent。generate_image 函数是一个简单的工具，用于模拟图像创建并返回模拟图像数据。image_generator_agent 负责根据接收到的文本提示使用此工具。artist_agent 的作用是首先构思一个创意图像提示。然后，它通过 AgentTool 包装器调用 image_generator_agent。AgentTool 充当桥梁，允许一个代理将另一个代理用作工具。当 artist_agent 调用 image_tool 时，AgentTool 会使用 artist 构思的提示来调用 image_generator_agent。image_generator_agent 随后使用该提示调用 generate_image 函数。最后，生成的图像（或模拟数据）通过代理返回给上级。这种架构展示了一种分层代理系统，其中上级代理协调下级专用代理执行任务。 

The provided code segment exemplifies the "Agent as a Tool" paradigm within the Google ADK, enabling an agent to utilize the capabilities of another agent in a manner analogous to function invocation.   Specifically, t he code defines an image generation system using Google's LlmAgent and AgentTool classes. It consists of two agents: a parent artist_agent and a sub-agent image_generator_agent. The generate_image function is a simple tool that simulates image creation, returning mock image data. The image_generator_agent is responsible for using this tool based on a text prompt it receives. The artist_agent's role is to first invent a creative image prompt. It then calls the image_generator_agent through an AgentTool wrapper. The AgentTool acts as a bridge, allowing one agent to use another agent as a tool. When the artist_agent calls the image_tool, the AgentTool invokes the image_generator_agent with the artist's invented prompt. The image_generator_agent then uses the generate_image function with that prompt. Finally, the generated image (or mock data) is returned back up through the agents. This architecture demonstrates a layered agent system where a higher-level agent orchestrates a lower-level, specialized agent to perform a task.

from google.adk.agents import LlmAgent from google.adk.tools import agent_tool from google.genai import types # 1. A simple function tool for the core capability. # This follows the best practice of separating actions from reasoning. def generate_image(prompt: str) -> dict:    """    Generates an image based on a textual prompt.    Args:        prompt: A detailed description of the image to generate.    Returns:        A dictionary with the status and the generated image bytes.    """    print(f"TOOL: Generating image for prompt: '{prompt}'")    # In a real implementation, this would call an image generation API.    # For this example, we return mock image data.    mock_image_bytes = b"mock_image_data_for_a_cat_wearing_a_hat"    return {        "status": "success",        # The tool returns the raw bytes, the agent will handle the Part creation.        "image_bytes": mock_image_bytes,        "mime_type": "image/png"    } # 2. Refactor the ImageGeneratorAgent into an LlmAgent. # It now correctly uses the input passed to it. image_generator_agent = LlmAgent(    name="ImageGen",    model="gemini-2.0-flash",    description="Generates an image based on a detailed text prompt.",    instruction=(        "You are an image generation specialist. Your task is to take the user's request "        "and use the `generate_image` tool to create the image. "        "The user's entire request should be used as the 'prompt' argument for the tool. "        "After the tool returns the image bytes, you MUST output the image."    ),    tools=[generate_image] ) # 3. Wrap the corrected agent in an AgentTool. # The description here is what the parent agent sees. image_tool = agent_tool.AgentTool(    agent=image_generator_agent,    description="Use this tool to generate an image. The input should be a descriptive prompt of the desired image." ) # 4. The parent agent remains unchanged. Its logic was correct. artist_agent = LlmAgent(    name="Artist",    model="gemini-2.0-flash",    instruction=(        "You are a creative artist. First, invent a creative and descriptive prompt for an image. "        "Then, use the `ImageGen` tool to generate the image using your prompt."    ),    tools=[image_tool] )

概览

At a Glance

问题：  复杂问题往往超出单个基于逻辑学习模型（LLM）的整体智能体的能力范围。单个智能体可能缺乏处理多方面任务所需的各种专业技能或特定工具。这种局限性会造成瓶颈，降低系统的整体效率和可扩展性。因此，处理复杂的多领域目标会变得效率低下，并可能导致结果不完整或不理想。

What:  Complex problems often exceed the capabilities of a single, monolithic LLM-based agent. A solitary agent may lack the diverse, specialized skills or access to the specific tools needed to address all parts of a multifaceted task. This limitation creates a bottleneck, reducing the system's overall effectiveness and scalability. As a result, tackling sophisticated, multi-domain objectives becomes inefficient and can lead to incomplete or suboptimal outcomes.

原因：  多智能体协作模式通过构建一个由多个协作智能体组成的系统，提供了一种标准化的解决方案。它将复杂问题分解成更小、更易于管理的子问题。每个子问题都分配给一个具备特定工具和能力的专用智能体来解决。这些智能体通过预定义的通信协议和交互模型（例如顺序交接、并行工作流或层级委派）协同工作。这种智能体分布式方法能够产生协同效应，使团队能够实现单个智能体无法达成的目标。

Why:  The Multi-Agent Collaboration pattern offers a standardized solution by creating a system of multiple, cooperating agents. A complex problem is broken down into smaller, more manageable sub-problems. Each sub-problem is then assigned to a specialized agent with the precise tools and capabilities required to solve it. These agents work together through defined communication protocols and interaction models like sequential handoffs, parallel workstreams, or hierarchical delegation. This agentic, distributed approach creates a synergistic effect, allowing the group to achieve outcomes that would be impossible for any single agent.

经验法则：  当任务过于复杂，单个智能体无法完成，且可以分解为需要专门技能或工具的多个子任务时，应使用此模式。它非常适合那些能够受益于多元化专业知识、并行处理或多阶段结构化工作流程的问题，例如复杂的调研分析、软件开发或创意内容创作。

Rule of thumb:  Use this pattern when a task is too complex for a single agent and can be decomposed into distinct sub-tasks requiring specialized skills or tools. It is ideal for problems that benefit from diverse expertise, parallel processing, or a structured workflow with multiple stages, such as complex research and analysis, software development, or creative content generation.

可视化摘要

Visual summary

图3：多智能体设计模式

Fig.3: Multi-Agent design pattern

要点总结

Key Takeaways

• 多智能体协作是指多个智能体共同协作以实现共同目标。
• Multi-agent collaboration involves multiple agents working together to achieve a common goal.
• 这种模式利用了专门的角色、分布式任务和 代理间通信。
• This pattern leverages specialized roles, distributed tasks, and inter-agent communication.
• 协作可以采取顺序交接、并行处理、辩论或层级结构等形式。
• Collaboration can take forms like sequential handoffs, parallel processing, debate, or hierarchical structures.
• 这种模式非常适合需要多种专业知识或多个不同阶段的复杂问题。
• This pattern is ideal for complex problems requiring diverse expertise or multiple distinct stages.

结论

Conclusion

本章探讨了多智能体协作模式，展示了在系统中协调多个专业智能体的优势。 我们考察了各种协作模型，强调了该模式在解决不同领域复杂、多方面问题中的关键作用。理解智能体协作自然而然地会引出对其与外部环境交互的探究。   

This chapter explored the Multi-Agent Collaboration pattern, demonstrating the benefits of orchestrating multiple specialized agents within systems.   We examined various collaboration models, emphasizing the pattern's essential role in addressing complex, multifaceted problems across diverse domains.   Understanding agent collaboration naturally leads to an inquiry into their interactions with the external environment.

参考

References

1. 多智能体协作机制：LLM综述， https://arxiv.org/abs/2501.06322  
2. Multi-Agent Collaboration Mechanisms: A Survey of LLMs, https://arxiv.org/abs/2501.06322  
3. 多智能体系统——协作的力量， https://aravindakumar.medium.com/introducing-multi-agent-frameworks-the-power-of-collaboration-e9db31bba1b6  
4. Multi-Agent System — The Power of Collaboration, https://aravindakumar.medium.com/introducing-multi-agent-frameworks-the-power-of-collaboration-e9db31bba1b6  

第八章  ：内存管理

Chapter  8: Memory Management

有效的内存管理对于智能体保留信息至关重要。 与人类一样，智能体需要不同类型的记忆才能高效运行。本章将深入探讨内存管理，重点关注智能体的即时（短期）记忆和持久（长期）记忆需求。   

Effective memory management is crucial for intelligent agents to retain information.   Agents require different types of memory, much like humans, to operate efficiently.   This chapter delves into memory management, specifically addressing the immediate (short-term) and persistent (long-term) memory requirements of agents.

在智能体系统中，记忆指的是智能体保留和利用过去交互、观察和学习经验中信息的能力。 这种能力使智能体能够做出明智的决策、保持对话上下文并随着时间的推移而不断改进。智能体记忆通常分为两大类：   

In agent systems, memory refers to an agent's ability to retain and utilize information from past interactions, observations, and learning experiences.   This capability allows agents to make informed decisions, maintain conversational context, and improve over time.   Agent memory is generally categorized into two main types:

• 短期记忆（上下文记忆）： 与工作记忆类似，它存储当前正在处理或最近访问过的信息。对于使用大型语言模型（LLM）的智能体而言，短期记忆主要存在于上下文窗口中。该窗口包含最近的消息、智能体的回复、工具使用结果以及智能体对当前交互的反思，所有这些都会影响LLM的后续响应和操作。上下文窗口的容量有限，限制了智能体可以直接访问的近期信息量。高效的短期记忆管理需要将最相关的信息保留在这个有限的空间内，例如通过总结较早的对话片段或强调关键细节等技术。具有“长上下文”窗口的模型的出现，只是简单地扩展了短期记忆的容量，允许在单次交互中存储更多信息。然而，这种上下文仍然是短暂的，一旦会话结束就会丢失，而且每次都进行处理既耗时又低效。因此，智能体需要不同的记忆类型来实现真正的持久性，回忆过去交互中的信息，并构建持久的知识库。 
• Short-Term Memory (Contextual Memory):   Similar to working memory, this holds information currently being processed or recently accessed. For agents using large language models (LLMs), short-term memory primarily exists within the context window. This window contains recent messages, agent replies, tool usage results, and agent reflections from the current interaction, all of which inform the LLM's subsequent responses and actions. The context window has a limited capacity, restricting the amount of recent information an agent can directly access. Efficient short-term memory management involves keeping the most relevant information within this limited space, possibly through techniques like summarizing older conversation segments or emphasizing key details. The advent of models with 'long context' windows simply expands the size of this short-term memory, allowing more information to be held within a single interaction. However, this context is still ephemeral and is lost once the session concludes, and it can be costly and inefficient to process every time. Consequently, agents require separate memory types to achieve true persistence, recall information from past interactions, and build a lasting knowledge base.
• 长期记忆（持久记忆）：它充当智能体在各种 交互、任务或较长时间内 需要保留的信息存储库 ，类似于长期知识库。数据通常存储在智能体直接处理环境之外，例如数据库、知识图谱或向量数据库中。在向量数据库中，信息被转换为数值向量并存储，使智能体能够基于语义相似性而非精确的关键词匹配来检索数据，这一过程称为语义搜索。当智能体需要从长期记忆中获取信息时，它会查询外部存储，检索相关数据，并将其整合到短期上下文中以供立即使用，从而将先前的知识与当前交互相结合。      
• Long-Term Memory (Persistent Memory):  This acts as a repository for information agents need to retain across various interactions , tasks, or extended periods, akin to long-term knowledge bases.   Data is typically stored outside the agent's immediate processing environment, often in databases, knowledge graphs, or vector databases.   In vector databases, information is converted into numerical vectors and stored, enabling agents to retrieve data based on semantic similarity rather than exact keyword matches, a process known as semantic search.   When an agent needs information from long-term memory, it queries the external storage, retrieves relevant data, and integrates it into the short-term context for immediate use, thus combining prior knowledge with the current interaction.

实际应用及案例

Practical Applications & Use Cases

内存管理对于智能体跟踪信息并随着时间的推移智能地执行操作至关重要。 这对于智能体超越基本的问答能力至关重要。应用领域包括：   

Memory management is vital for agents to track information and perform intelligently over time.   This is essential for agents to surpass basic question-answering capabilities.   Applications include:

• 聊天机器人和对话式人工智能：  维持对话流畅性依赖于短期记忆。 聊天机器人需要记住用户之前的输入才能提供连贯的回复。长期记忆则使聊天机器人能够回忆起用户的偏好、过往的问题或之前的讨论，从而提供个性化和持续的互动。   
• Chatbots and Conversational AI:  Maintaining conversation flow relies on short-term memory.   Chatbots require remembering prior user inputs to provide coherent responses.   Long-term memory enables chatbots to recall user preferences, past issues, or prior discussions, offering personalized and continuous interactions.
• 面向任务的智能体：  管理多步骤任务的智能体需要短期记忆来跟踪之前的步骤、当前进度和总体目标。 这些信息可能存储在任务上下文或临时存储中。长期记忆对于访问不在当前上下文中的特定用户相关数据至关重要。   
• Task-Oriented Agents:  Agents managing multi-step tasks need short-term memory to track previous steps, current progress, and overall goals.   This information might reside in the task's context or temporary storage.   Long-term memory is crucial for accessing specific user-related data not in the immediate context.
• 个性化体验：  提供定制化互动服务的客服人员会利用长期记忆来存储和检索用户的偏好、过往行为和个人信息。 这使得客服人员能够根据这些信息调整他们的回复和建议。 
• Personalized Experiences:  Agents offering tailored interactions utilize long-term memory to store and retrieve user preferences, past behaviors, and personal information.   This allows agents to adapt their responses and suggestions.
• 学习与改进：  智能体可以通过从过去的交互中学习来改进自身表现。 成功的策略、错误和新信息都会存储在长期记忆中，从而促进未来的适应。强化学习智能体 正是以这种方式存储学习到的策略或知识 。   
• Learning and Improvement:  Agents can refine their performance by learning from past interactions.   Successful strategies, mistakes, and new information are stored in long-term memory, facilitating future adaptations.   Reinforcement learning agents store learned strategies or knowledge  in  this way.
• 信息检索（RAG）：  旨在回答问题的智能体访问知识库（即其长期记忆），这通常 通过 检索增强生成（RAG）技术实现。智能体检索相关文档或数据以指导其回答。
• Information Retrieval (RAG):  Agents designed for answering questions access a knowledge base, their long-term memory, often implemented with in Retrieval Augmented Generation (RAG). The agent retrieves relevant documents or data to inform its responses.
• 自主系统：  机器人或自动驾驶汽车需要记忆地图、路线、物体位置和已学习的行为。 这包括用于存储当前环境信息的短期记忆和用于存储一般环境知识的长期记忆。 
• Autonomous Systems:  Robots or self-driving cars require memory for maps, routes, object locations, and learned behaviors.   This involves short-term memory for immediate surroundings and long-term memory for general environmental knowledge.

记忆使智能体能够保存历史记录、学习、个性化交互以及管理复杂的、随时间变化的问题。

Memory enables agents to maintain history, learn, personalize interactions, and manage complex, time-dependent problems.

实战代码 ：  Google Agent Developer Kit (ADK) 中的内存 管理

Hands-On Code : Memory Management  in Google Agent Developer Kit (ADK)

Google Agent Developer Kit (ADK) 提供了一种结构化的方法来管理上下文和内存，其中包含用于实际应用的组件。 对于需要保留信息的代理来说，深入理解 ADK 的会话、状态和内存至关重要。 

The Google Agent Developer Kit (ADK) offers a structured method for managing context and memory, including components for practical application.   A solid grasp of ADK's Session, State, and Memory is vital for building agents that need to retain information.

正如人际互动一样，智能体也需要能够回忆起之前的交流内容，才能进行连贯自然的对话。ADK 通过三个核心概念及其相关服务简化了上下文管理。 

Just as in human interactions, agents require the ability to recall previous exchanges to conduct coherent and natural conversations.   ADK simplifies context management through three core concepts and their associated services.

与代理的每一次交互都可以视为一个独立的对话线程。 代理可能需要访问先前交互中的数据。ADK对此的结构化处理如下：   

Every interaction with an agent can be considered a unique conversation thread.   Agents might need to access data from earlier interactions.   ADK structures this as follows:

• 会话：  一个单独的聊天线程，用于记录特定交互的消息和操作（事件），并存储与该对话相关的临时数据（状态）。
• Session:  An individual chat thread that logs messages and actions (Events) for that specific interaction, also storing temporary data (State) relevant to that conversation.
• 状态（session.state）：  存储在会话中的数据，包含仅与当前活动聊天线程相关的信息。
• State (session.state):  Data stored within a Session, containing information relevant only to the current, active chat thread.
• 记忆：  一个可搜索的信息库，信息来源于各种过去的聊天记录或外部来源，可作为超出当前对话范围的数据检索资源。
• Memory:  A searchable repository of information sourced from various past chats or external sources, serving as a resource for data retrieval beyond the immediate conversation.

ADK 提供专用服务来管理构建复杂、有状态且具有上下文感知能力的代理所必需的关键组件。SessionService 通过处理聊天线程（Session 对象）的启动、记录和终止来管理它们，而 MemoryService 则负责长期知识（Memory）的存储和检索。 

ADK provides dedicated services for managing critical components essential for building complex, stateful, and context-aware agents.   The SessionService manages chat threads (Session objects) by handling their initiation, recording, and termination, while the MemoryService oversees the storage and retrieval of long-term knowledge (Memory).

SessionService 和 MemoryService 都提供多种配置选项，允许用户根据应用程序需求选择存储方式。 内存存储选项可用于测试，但重启后数据将丢失。为了实现持久存储和可扩展性，ADK 还支持数据库和云服务。   

Both the SessionService and MemoryService offer various configuration options, allowing users to choose storage methods based on application needs.   In-memory options are available for testing purposes, though data will not persist across restarts.   For persistent storage and scalability, ADK also supports database and cloud-based services.

会话：跟踪每次聊天

Session: Keeping Track of Each Chat

在 ADK 中，Session 对象旨在跟踪和管理单个聊天线程。 当用户与客服人员发起对话时，SessionService 会生成一个 Session 对象，其表示形式为 `google.adk.sessions.Session`。该对象封装了与特定对话线程相关的所有数据，包括唯一标识符（id、app_name、user_id）、按时间顺序排列的事件记录（以 Event 对象形式呈现）、用于存储会话特定临时数据（称为状态）的区域，以及指示上次更新的时间戳（last_update_time）。开发人员通常通过 SessionService 间接与 Session 对象交互。SessionService负责管理对话会话的生命周期，包括发起新会话、恢复之前的会话、记录会话活动（包括状态更新）、识别活动会话以及管理会话数据的删除。ADK提供了多种 SessionService 实现，它们采用不同的存储机制来存储会话历史记录和临时数据，例如 InMemorySessionService，它适用于测试，但无法在应用程序重启后保持数据持久性。         

A Session object in ADK is designed to track and manage individual chat threads.   Upon initiation of a conversation with an agent, the SessionService generates a Session object, represented as `google.adk.sessions.Session`.   This object encapsulates all data relevant to a specific conversation thread, including unique identifiers (id, app_name, user_id), a chronological record of events as Event objects, a storage area for session-specific temporary data known as state, and a timestamp indicating the last update (last_update_time).   Developers typically interact with Session objects indirectly through the SessionService.   The SessionService is responsible for managing the lifecycle of conversation sessions, which includes initiating new sessions, resuming previous sessions, recording session activity (including state updates), identifying active sessions, and managing the removal of session data.   The ADK provides several SessionService implementations with varying storage mechanisms for session history and temporary data, such as the InMemorySessionService, which is suitable for testing but does not provide data persistence across application restarts.

# Example: Using InMemorySessionService # This is suitable for local development and testing where data # persistence across application restarts is  not required. from google.adk.sessions import InMemorySessionService session_service = InMemorySessionService()

如果您需要将数据可靠地保存到您管理的数据库中，可以使用 DatabaseSessionService。

Then there's DatabaseSessionService if you want reliable saving to a database you manage.

# Example: Using DatabaseSessionService # This is suitable for production or development requiring persistent storage. # You need to configure a database URL (e.g., for SQLite, PostgreSQL, etc.). # Requires: pip install google-adk[sqlalchemy] and a database driver (e.g., psycopg2 for PostgreSQL) from google.adk.sessions import DatabaseSessionService # Example using a local SQLite file: db_url = "sqlite:///./my_agent_data.db" session_service = DatabaseSessionService(db_url=db_url)

此外，还有 VertexAiSessionService，它使用 Vertex AI 基础设施在 Google Cloud 上实现可扩展的生产。

Besides, there's VertexAiSessionService which uses Vertex AI infrastructure for scalable production on Google Cloud.

# Example: Using VertexAiSessionService # This is suitable for scalable production on Google Cloud Platform, leveraging # Vertex AI infrastructure for session management. # Requires: pip install google-adk[vertexai] and GCP setup/authentication from google.adk.sessions import VertexAiSessionService PROJECT_ID = "your-gcp-project-id" # Replace with your GCP project ID LOCATION = "us-central1" # Replace with your desired GCP location # The app_name used with this service should correspond to the Reasoning Engine ID or name REASONING_ENGINE_APP_NAME = "projects/your-gcp-project-id/locations/us-central1/reasoningEngines/your-engine-id" # Replace with your Reasoning Engine resource name session_service = VertexAiSessionService(project=PROJECT_ID, location=LOCATION) # When using this service, pass REASONING_ENGINE_APP_NAME to service methods: # session_service.create_session(app_name=REASONING_ENGINE_APP_NAME, ...) # session_service.get_session(app_name=REASONING_ENGINE_APP_NAME, ...) # session_service.append_event(session, event, app_name=REASONING_ENGINE_APP_NAME) # session_service.delete_session(app_name=REASONING_ENGINE_APP_NAME, ...)

选择合适的 SessionService 至关重要，因为它决定了代理的交互历史和临时数据的存储方式及其持久性。

Choosing an appropriate SessionService is crucial as it determines how the agent's interaction history and temporary data are stored and their persistence.

每次消息交换都涉及一个循环过程：接收到消息后，Runner 使用 SessionService 获取或建立会话，代理使用会话的上下文（状态和历史交互）处理消息，代理生成响应并可能更新状态，Runner 将此更新封装为事件，session_service.append_event 方法记录新事件并更新存储中的状态。 然后，会话等待下一条消息。理想情况下，交互结束后应使用 delete_session 方法终止会话。此过程说明了 SessionService 如何通过管理会话特定的历史记录和临时数据来维持连续性。     

Each message exchange involves a cyclical process: A message is received, the Runner retrieves or establishes a Session using the SessionService, the agent processes the message using the Session's context (state and historical interactions), the agent generates a response and may update the state, the Runner encapsulates this as an Event, and the session_service.append_event method records the new event and updates the state in storage.   The Session then awaits the next message.   Ideally, the delete_session method is employed to terminate the session when the interaction concludes.   This process illustrates how the SessionService maintains continuity by managing the Session-specific history and temporary data.

状态：会议草稿本

State: The Session's Scratchpad

在 ADK 中，每个会话（代表一个聊天线程）都包含一个状态组件，类似于客服人员在该特定对话期间的临时工作记忆。session.events 记录整个聊天历史记录，而 session.state 则存储并更新与当前聊天相关的动态数据点。 

In the ADK, each Session, representing a chat thread, includes a state component akin to an agent's temporary working memory for the duration of that specific conversation.   While session.events logs the entire chat history, session.state stores and updates dynamic data points relevant to the active chat.

从本质上讲，session.state 的作用类似于字典，以键值对的形式存储数据。 其核心功能是使代理能够保留和管理对流畅对话至关重要的细节信息，例如用户偏好、任务进度、增量数据收集或影响后续代理操作的条件标志。 

Fundamentally, session.state operates as a dictionary, storing data as key-value pairs.   Its core function is to enable the agent to retain and manage details essential for coherent dialogue, such as user preferences, task progress, incremental data collection, or conditional flags influencing subsequent agent actions.

状态结构由字符串键和可序列化的 Python 类型值组成，这些类型包括字符串、数字、布尔值、列表以及包含这些基本类型的字典。 状态是动态的，会在整个对话过程中不断演变。这些变化的持久性取决于配置的 SessionService。   

The state’s structure comprises string keys paired with values of serializable Python types, including strings, numbers, booleans, lists, and dictionaries containing these basic types.   State is dynamic, evolving throughout the conversation.   The permanence of these changes depends on the configured SessionService.

可以通过使用键前缀来定义数据范围和持久性，从而实现状态组织。 没有前缀的键是会话特定的。   

State organization can be achieved using key prefixes to define data scope and persistence.   Keys without prefixes are session-specific.  

• 用户前缀将数据与所有会话中的用户 ID 关联起来。  
• The user: prefix associates data with a user ID across all sessions.  
• app:前缀表示应用程序所有用户共享的数据。  
• The app: prefix designates data shared among all users of the application.  
• temp: 前缀表示数据仅在当前处理轮次有效，不会持久存储。  
• The temp: prefix indicates data valid only for the current processing turn and is not persistently stored.  

代理通过单个 session.state 字典访问所有状态数据。SessionService 负责处理数据检索、合并和持久化。当通过 session_service.append_event() 将事件添加到会话历史记录时，状态应更新。这确保了准确的跟踪、持久化服务中的正确保存以及对状态变更的安全处理。     

The agent accesses all state data through a single session.state dictionary.   The SessionService handles data retrieval, merging, and persistence.   State should be updated upon adding an Event to the session history via session_service.append_event().   This ensures accurate tracking, proper saving in persistent services, and safe handling of state changes.

1. 简单方法：使用 output_key（用于代理文本回复）：  如果您只想将代理的最终文本回复直接保存到状态中，这是最简单的方法。设置 LlmAgent 时，只需指定要使用的 output_key 即可。Runner 会识别此设置，并在追加事件时自动创建必要的操作，将回复保存到状态中。 下面我们来看一个通过 output_key 更新状态的代码示例。 
2. The Simple Way: Using output_key (for Agent Text Replies):  This is the easiest method if you just want to save your agent's final text response directly into the state. When you set up your LlmAgent, just tell it the output_key you want to use. The Runner sees this and automatically creates the necessary actions to save the response to the state when it appends the event.   Let's look at a code example demonstrating state update via output_key.

# Import necessary classes from the Google Agent Developer Kit (ADK) from google.adk.agents import LlmAgent from google.adk.sessions import InMemorySessionService, Session from google.adk.runners import Runner from google.genai.types import Content, Part # Define an LlmAgent with an output_key. greeting_agent = LlmAgent(    name="Greeter",    model="gemini-2.0-flash",    instruction="Generate a short, friendly greeting.",    output_key="last_greeting" ) # --- Setup Runner and Session --- app_name, user_id, session_id = "state_app", "user1", "session1" session_service = InMemorySessionService() runner = Runner(    agent=greeting_agent,    app_name=app_name,    session_service=session_service ) session = session_service.create_session(    app_name=app_name,    user_id=user_id,    session_id=session_id ) print(f"Initial state: {session.state}") # --- Run the Agent --- user_message = Content(parts=[Part(text="Hello")]) print("\n--- Running the agent ---") for event in runner.run(    user_id=user_id,    session_id=session_id,    new_message=user_message ):    if event.is_final_response():      print("Agent responded.") # --- Check Updated State --- # Correctly check the state *after* the runner has finished processing all events. updated_session = session_service.get_session(app_name, user_id, session_id) print(f"\nState after agent run: {updated_session.state}")

在后台，Runner 会查看您的 output_key，并在调用 append_event 时自动创建带有 state_delta 的必要操作。

Behind the scenes, the Runner sees your output_key and automatically creates the necessary actions with a state_delta when it calls append_event.

2. 标准方法：使用 EventActions.state_delta（用于更复杂的更新）：  当您需要执行更复杂的操作时——例如同时更新多个键、保存非文本内容、针对特定范围（例如 user: 或 app:）进行更新，或者执行与代理最终文本回复无关的更新——您需要手动构建一个状态更改字典（state_delta），并将其包含在您要追加的事件的 EventActions 中。让 我们来看一个例子：
3. The Standard Way: Using EventActions.state_delta (for More Complicated Updates):  For times when you need to do more complex things – like updating several keys at once, saving things that aren't just text, targeting specific scopes like user: or app:, or making updates that aren't tied to the agent's final text reply – you'll manually build a dictionary of your state changes (the state_delta) and include it within the EventActions of the Event you're appending. Let 's look at one example:

import time from google.adk.tools.tool_context import ToolContext from google.adk.sessions import InMemorySessionService # --- Define the Recommended Tool-Based Approach --- def log_user_login(tool_context: ToolContext) -> dict:    """    Updates the session state upon a user login event.    This tool encapsulates all state changes related to a user login.    Args:        tool_context: Automatically provided by ADK, gives access to session state.    Returns:        A dictionary confirming the action was successful.    """    # Access the state directly through the provided context.    state = tool_context.state      # Get current values or defaults, then update the state.    # This is much cleaner and co-locates the logic.    login_count = state.get("user:login_count", 0) + 1    state["user:login_count"] = login_count    state["task_status"] = "active"    state["user:last_login_ts"] = time.time()    state["temp:validation_needed"] = True      print("State updated from within the `log_user_login` tool.")      return {        "status": "success",        "message": f"User login tracked. Total logins: {login_count}."    } # --- Demonstration of Usage --- # In a real application, an LLM Agent would decide to call this tool. # Here, we simulate a direct call for demonstration purposes. # 1. Setup session_service = InMemorySessionService() app_name, user_id, session_id = "state_app_tool", "user3", "session3" session = session_service.create_session(    app_name=app_name,    user_id=user_id,    session_id=session_id,    state={"user:login_count": 0, "task_status": "idle"} ) print(f"Initial state: {session.state}") # 2. Simulate a tool call (in a real app, the ADK Runner does this) # We create a ToolContext manually just for this standalone example. from google.adk.tools.tool_context import InvocationContext mock_context = ToolContext(    invocation_context=InvocationContext(        app_name=app_name, user_id=user_id, session_id=session_id,        session=session, session_service=session_service    ) ) # 3. Execute the tool log_user_login(mock_context) # 4. Check the updated state updated_session = session_service.get_session(app_name, user_id, session_id) print(f"State after tool execution: {updated_session.state}") # Expected output will show the same state change as the # "Before" case, # but the code organization is significantly cleaner # and more robust.

这段代码演示了一种基于工具的方法来管理应用程序中的用户会话状态。它定义了一个名为 `log_user_login`的函数 ，  该函数充当工具的角色。此工具负责在用户登录时更新会话状态。

This code demonstrates a tool-based approach for managing user session state in an application. It defines a function log_user_login ,  which acts as a tool. This tool is responsible for updating the session state when a user logs in.

该函数接受  ADK 提供的ToolContext对象，以访问和修改会话的状态字典。在工具内部，它递增 user:login_count ，将t ask_status设置 为“active”，记录user:last_login_ts  （时间戳），并添加一个临时标志temp:validation_needed 。

The function takes a ToolContext  object, provided by the ADK, to access and modify the session's state dictionary. Inside the tool, it increments a user:login_count , sets the t ask_status  to "active", records the user:last_login_ts  (timestamp) , and adds a temporary flag temp:validation_needed .

代码的演示部分模拟了该工具的使用方式。它设置了一个内存会话服务，并创建了一个具有预定义状态的初始会话。然后手动创建一个 ToolContext  ，以模拟 ADK Runner 执行该工具的环境。使用该模拟上下文调用 ` log_user_login`  函数。最后，代码再次检索会话，以显示状态已因工具的执行而更新。其目的是展示将​​状态更改封装在工具内部如何使代码更简洁、更结构化，相比之下，直接在工具外部操作状态则更为困难 。

The demonstration part of the code simulates how this tool would be used. It sets up an in-memory session service and creates an initial session with some predefined state. A ToolContext  is then manually created to mimic the environment in which the ADK Runner would execute the tool. The log_user_login  function is called with this mock context. Finally, the code retrieves the session again to show that the state has been updated by the tool's execution. The goal is to show how encapsulating state changes within tools makes the code cleaner and more organized compared to directly manipulating state outside of tools .

请注意， 强烈建议不要在获取会话后直接修改 `session.state` 字典，因为这会绕过标准的事件处理机制。 此类直接修改不会记录在会话的事件历史记录中，可能不会被选定的 `SessionService` 持久化，可能会导致并发问题，并且不会更新时间戳等重要元数据。更新会话状态的推荐方法是使用 `LlmAgent` 的 `output_key` 参数（专门用于代理的最终文本响应），或者在通过 `session_service.append_event()` 追加事件时，在 `EventActions.state_delta` 中包含状态更改。`session.state`主要用于读取现有数据。     

Note that d irect modification of the `session.state` dictionary after retrieving a session is strongly discouraged as it bypasses the standard event processing mechanism.   Such direct changes will not be recorded in the session's event history, may not be persisted by the selected `SessionService`, could lead to concurrency issues, and will not update essential metadata such as timestamps.   The recommended methods for updating the session state are using the `output_key` parameter on an `LlmAgent` (specifically for the agent's final text responses) or including state changes within `EventActions.state_delta` when appending an event via `session_service.append_event()`.   The `session.state` should primarily be used for reading existing data.

总而言之，在设计状态时，要保持简单，使用基本数据类型，给键起清晰的名称并正确使用前缀，避免深度嵌套，并且始终使用 append_event 过程更新状态。

To recap, when designing your state, keep it simple, use basic data types, give your keys clear names and use prefixes correctly, avoid deep nesting, and always update state using the append_event process.

记忆：使用 MemoryService 进行长期记忆

Memory: Long-Term Knowledge with MemoryService

在代理系统中，会话组件维护着当前聊天历史记录（事件）和特定于单个对话的临时数据（状态）。 然而，为了使代理能够在多次交互中保留信息或访问外部数据，长期知识管理必不可少。记忆服务 (MemoryService) 正是为此而生。   

In agent systems, the Session component maintains a record of the current chat history (events) and temporary data (state) specific to a single conversation.   However, for agents to retain information across multiple interactions or access external data, long-term knowledge management is necessary.   This is facilitated by the MemoryService.

# Example: Using InMemoryMemoryService # This is suitable for local development and testing where data # persistence across application restarts is not required. # Memory content is lost when the app stops. from google.adk.memory import InMemoryMemoryService memory_service = InMemoryMemoryService()

会话和状态可以理解为单个聊天会话的短期记忆，而由 MemoryService 管理的长期知识库则作为一个持久且可搜索的存储库。 该存储库可能包含来自多个历史交互或外部来源的信息。MemoryService由 BaseMemoryService 接口定义，它为管理这种可搜索的长期知识库建立了一个标准。其主要功能包括添加信息（涉及使用 add_session_to_memory 方法从会话中提取内容并将其存储）和检索信息（允许代理使用 search_memory 方法查询存储库并接收相关数据）。     

Session and State can be conceptualized as short-term memory for a single chat session, whereas the Long-Term Knowledge managed by the MemoryService functions as a persistent and searchable repository.   This repository may contain information from multiple past interactions or external sources.   The MemoryService, as defined by the BaseMemoryService interface, establishes a standard for managing this searchable, long-term knowledge.   Its primary functions include adding information, which involves extracting content from a session and storing it using the add_session_to_memory method, and retrieving information, which allows an agent to query the store and receive relevant data using the search_memory method.

ADK 提供了多种实现方案来创建这种长期知识库。InMemoryMemoryService 提供了一种适用于测试的临时存储解决方案，但数据在应用程序重启后会丢失。对于生产环境，通常使用 VertexAiRagMemoryService。该服务利用了 Google Cloud 的检索增强生成 (RAG) 服务，从而实现了可扩展、持久且语义化的搜索功能 （另请参阅关于 RAG 的第 14 章）。     

The ADK offers several implementations for creating this long-term knowledge store.   The InMemoryMemoryService provides a temporary storage solution suitable for testing purposes, but data is not preserved across application restarts.   For production environments, the VertexAiRagMemoryService is typically utilized.   This service leverages Google Cloud's Retrieval Augmented Generation (RAG) service, enabling scalable, persistent, and semantic search capabilities  ( Also, refer to the chapter 14 on RAG ).

# Example: Using VertexAiRagMemoryService # This is suitable for scalable production on GCP, leveraging # Vertex AI RAG (Retrieval Augmented Generation) for persistent, # searchable memory. # Requires: pip install google-adk[vertexai], GCP # setup/authentication, and a Vertex AI RAG Corpus. from google.adk.memory import VertexAiRagMemoryService # The resource name of your Vertex AI RAG Corpus RAG_CORPUS_RESOURCE_NAME = "projects/your-gcp-project-id/locations/us-central1/ragCorpora/your-corpus-id" # Replace with your Corpus resource name # Optional configuration for retrieval behavior SIMILARITY_TOP_K = 5 # Number of top results to retrieve VECTOR_DISTANCE_THRESHOLD = 0.7 # Threshold for vector similarity memory_service = VertexAiRagMemoryService(    rag_corpus=RAG_CORPUS_RESOURCE_NAME,    similarity_top_k=SIMILARITY_TOP_K,    vector_distance_threshold=VECTOR_DISTANCE_THRESHOLD ) # When using this service, methods like add_session_to_memory # and search_memory will interact with the specified Vertex AI # RAG Corpus.

动手实践：LangChain 和 LangGraph 中的内存管理

Hands-on code: Memory Management in LangChain and LangGraph

在 LangChain 和 LangGraph 中，记忆功能是创建智能且自然流畅的对话式应用程序的关键组件。它使 AI 代理能够记住过去交互的信息，从反馈中学习，并适应用户偏好。LangChain 的记忆功能通过引用存储的历史记录来丰富当前的提示，并将最近的交流记录下来以供将来使用，从而为实现这一目标奠定了基础。随着代理处理的任务越来越复杂，这项功能对于提高效率和提升用户满意度都至关重要。

In LangChain and LangGraph, Memory is a critical component for creating intelligent and natural-feeling conversational applications. It allows an AI agent to remember information from past interactions, learn from feedback, and adapt to user preferences. LangChain's memory feature provides the foundation for this by referencing a stored history to enrich current prompts and then recording the latest exchange for future use. As agents handle more complex tasks, this capability becomes essential for both efficiency and user satisfaction.

短期记忆：短期记忆的  作用域限定于线程，这意味着它跟踪单个会话或线程内的正在进行的对话。它提供即时上下文，但完整的历史记录可能会超出 LLM 的上下文窗口，从而可能导致错误或性能下降。LangGraph 将短期记忆作为代理状态的一部分进行管理，并通过检查点持久化，从而允许随时恢复线程。

Short-Term Memory:  This is thread-scoped, meaning it tracks the ongoing conversation within a single session or thread. It provides immediate context, but a full history can challenge an LLM's context window, potentially leading to errors or poor performance. LangGraph manages short-term memory as part of the agent's state, which is persisted via a checkpointer, allowing a thread to be resumed at any time.

长期记忆：长期记忆  用于存储用户特定数据或应用程序级别的数据，这些数据跨会话存储，并在不同的对话线程之间共享。它保存在自定义的“命名空间”中，并且可以在任何线程中随时调用。LangGraph 提供用于保存和调用长期记忆的存储机制，使智能体能够无限期地保留知识。

Long-Term Memory:  This stores user-specific or application-level data across sessions and is shared between conversational threads. It is saved in custom "namespaces" and can be recalled at any time in any thread. LangGraph provides stores to save and recall long-term memories, enabling agents to retain knowledge indefinitely.

LangChain 提供了多种管理对话历史的工具，从手动控制到链内自动集成，应有尽有。

LangChain provides several tools for managing conversation history, ranging from manual control to automated integration within chains.

ChatMessageHistory：手动内存管理。 如果您想在正式的对话链之外，直接、简单地控制对话历史记录，ChatMessageHistory 类是理想之选。它允许您手动跟踪对话往来。

ChatMessageHistory: Manual Memory Management. For direct and simple control over a conversation's history outside of a formal chain, the ChatMessageHistory class is ideal. It allows for the manual tracking of dialogue exchanges.

from langchain.memory import ChatMessageHistory # Initialize the history object history = ChatMessageHistory() # Add user and AI messages history.add_user_message("I'm heading to New York next week.") history.add_ai_message("Great! It's a fantastic city.") # Access the list of messages print(history.messages)

ConversationBufferMemory：链式调用的自动记忆功能 。ConversationBufferMemory 是将记忆功能直接集成到链式调用中的常用选择。它会保存对话缓冲区，并将其提供给提示符。其行为可通过两个关键参数进行自定义：

ConversationBufferMemory: Automated Memory for Chains . For integrating memory directly into chains, ConversationBufferMemory is a common choice. It holds a buffer of the conversation and makes it available to your prompt. Its behavior can be customized with two key parameters:

• memory_key ：一个字符串，指定提示符中用于保存聊天记录的变量名。默认值为“history”。
• memory_key : A string that specifies the variable name in your prompt that will hold the chat history. It defaults to "history".
• return_messages ：一个布尔值，用于指定历史记录的格式。
• return_messages : A boolean that dictates the format of the history.

• 如果为 False（默认值），则返回一个格式化的字符串，这对于标准 LLM 来说是理想的。
• If False (the default), it returns a single formatted string, which is ideal for standard LLMs.
• 如果为 True，则返回消息对象列表，这是聊天模型的推荐格式。
• If True, it returns a list of message objects, which is the recommended format for Chat Models.

from langchain.memory import ConversationBufferMemory # Initialize memory memory = ConversationBufferMemory() # Save a conversation turn memory.save_context({"input": "What's the weather like?"}, {"output": "It's sunny today."}) # Load the memory as a string print(memory.load_memory_variables({}))

将此记忆集成到 LLMChain 中，可以让模型访问对话历史记录并提供与上下文相关的响应。

Integrating this memory into an LLMChain allows the model to access the conversation's history and provide contextually relevant responses

from langchain_openai import OpenAI from langchain.chains import LLMChain from langchain.prompts import PromptTemplate from langchain.memory import ConversationBufferMemory # 1. Define LLM and Prompt llm = OpenAI(temperature=0) template = """You are a helpful travel agent. Previous conversation: {history} New question: {question} Response:""" prompt = PromptTemplate.from_template(template) # 2. Configure Memory # The memory_key "history" matches the variable in the prompt memory = ConversationBufferMemory(memory_key="history") # 3. Build the Chain conversation = LLMChain(llm=llm, prompt=prompt, memory=memory) # 4. Run the Conversation response = conversation.predict(question="I want to book a flight.") print(response) response = conversation.predict(question="My name is Sam, by the way.") print(response) response = conversation.predict(question="What was my name again?") print(response)

为了提高聊天模型的有效性，建议通过设置 `return_messages=True` 来使用结构化的消息对象列表。

For improved effectiveness with chat models, it is recommended to use a structured list of message objects by setting `return_messages=True`.

from langchain_openai import ChatOpenAI from langchain.chains import LLMChain from langchain.memory import ConversationBufferMemory from langchain_core.prompts import (    ChatPromptTemplate,    MessagesPlaceholder,    SystemMessagePromptTemplate,    HumanMessagePromptTemplate, ) # 1. Define Chat Model and Prompt llm = ChatOpenAI() prompt = ChatPromptTemplate(    messages=[        SystemMessagePromptTemplate.from_template("You are a friendly assistant."),        MessagesPlaceholder(variable_name="chat_history"),        HumanMessagePromptTemplate.from_template("{question}")    ] ) # 2. Configure Memory # return_messages=True is essential for chat models memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True) # 3. Build the Chain conversation = LLMChain(llm=llm, prompt=prompt, memory=memory) # 4. Run the Conversation response = conversation.predict(question="Hi, I'm Jane.") print(response) response = conversation.predict(question="Do you remember my name?") print(response)

长期记忆的类型 ： 长期记忆使系统能够在不同的对话中保留信息，从而提供更深层次的背景信息和个性化体验。它可以分为三种类型，类似于人类记忆：

Types of Long-Term Memory : Long-term memory allows systems to retain information across different conversations, providing a deeper level of context and personalization. It can be broken down into three types analogous to human memory:

• 语义记忆：记住事实： 这涉及保留特定的事实和概念，例如用户偏好或领域知识。它用于为智能体的响应提供依据，从而实现更个性化和更相关的交互。这些信息可以作为持续更新的用户“个人资料”（JSON 文档）进行管理，也可以作为一系列独立事实文档进行管理。 
• Semantic Memory: Remembering Facts:   This involves retaining specific facts and concepts, such as user preferences or domain knowledge. It is used to ground an agent's responses, leading to more personalized and relevant interactions. This information can be managed as a continuously updated user "profile" (a JSON document) or as a "collection" of individual factual documents.
• 情景记忆：回忆经验： 这涉及回忆过去的事件或行为。对于人工智能体而言，情景记忆通常用于记住如何完成任务。在实践中，它通常通过 少样本示例提示来实现 ，智能体从过去成功的交互序列中学习，从而正确地执行任务。
• Episodic Memory: Remembering Experiences: This involves recalling past events or actions. For AI agents, episodic memory is often used to remember how to accomplish a task. In practice, it's frequently implemented through few-shot example prompting , where an agent learns from past successful interaction sequences to perform tasks correctly.
• 程序性记忆：规则记忆：   这是执行任务的方式记忆——智能体的核心指令和行为，通常包含在其系统提示中。智能体通常会修改自身的提示以进行适应和改进。一种有效的技术是 “反思”，  即向智能体显示其当前指令和最近的交互，然后要求其改进自身的指令。
• Procedural Memory: Remembering Rules:   This is the memory of how to perform tasks—the agent's core instructions and behaviors, often contained in its system prompt. It's common for agents to modify their own prompts to adapt and improve. An effective technique is "Reflection,"  where an agent is prompted with its current instructions and recent interactions, then asked to refine its own instructions.

以下是伪代码，演示了代理如何使用反射来更新存储在 LangGraph BaseStore 中的过程记忆。

Below is pseudo-code demonstrating how an agent might use reflection to update its procedural memory stored in a LangGraph BaseStore

# Node that updates the agent's instructions def update_instructions(state: State, store: BaseStore):    namespace = ("instructions",)    # Get the current instructions from the store    current_instructions = store.search(namespace)[0]      # Create a prompt to ask the LLM to reflect on the conversation    # and generate new, improved instructions    prompt = prompt_template.format(        instructions=current_instructions.value["instructions"],        conversation=state["messages"]    )      # Get the new instructions from the LLM    output = llm.invoke(prompt)    new_instructions = output['new_instructions']      # Save the updated instructions back to the store    store.put(("agent_instructions",), "agent_a", {"instructions": new_instructions}) # Node that uses the instructions to generate a response def call_model(state: State, store: BaseStore):    namespace = ("agent_instructions", )    # Retrieve the latest instructions from the store    instructions = store.get(namespace, key="agent_a")[0]      # Use the retrieved instructions to format the prompt    prompt = prompt_template.format(instructions=instructions.value["instructions"])    # ... application logic continues

LangGraph 将长期记忆以 JSON 文档的形式存储在存储库中。每个记忆都组织在一个自定义命名空间（类似于文件夹）和一个唯一的键（类似于文件名）下。这种层级结构便于信息的组织和检索。以下代码演示了如何使用 InMemoryStore 来存储、获取和搜索记忆。

LangGraph stores long-term memories as JSON documents in a store. Each memory is organized under a custom namespace (like a folder) and a distinct key (like a filename). This hierarchical structure allows for easy organization and retrieval of information. The following code demonstrates how to use InMemoryStore to put, get, and search for memories.

from langgraph.store.memory import InMemoryStore # A placeholder for a real embedding function def embed(texts: list[str]) -> list[list[float]]:    # In a real application, use a proper embedding model    return [[1.0, 2.0] for _ in texts] # Initialize an in-memory store. For production, use a database-backed store. store = InMemoryStore(index={"embed": embed, "dims": 2}) # Define a namespace for a specific user and application context user_id = "my-user" application_context = "chitchat" namespace = (user_id, application_context) # 1. Put a memory into the store store.put(    namespace,    "a-memory",  # The key for this memory    {        "rules": [            "User likes short, direct language",            "User only speaks English & python",        ],        "my-key": "my-value",    }, ) # 2. Get the memory by its namespace and key item = store.get(namespace, "a-memory") print("Retrieved Item:", item) # 3. Search for memories within the namespace, filtering by content # and sorting by vector similarity to the query. items = store.search(    namespace,    filter={"my-key": "my-value"},    query="language preferences" ) print("Search Results:", items)

顶点存储器库

Vertex Memory Bank

记忆库是 Vertex AI 代理引擎中的一项托管服务，它为代理提供持久的长期记忆。该服务使用 Gemini 模型异步分析对话历史记录，以提取关键事实和用户偏好。

Memory Bank, a managed service in the Vertex AI Agent Engine, provides agents with persistent, long-term memory. The service uses Gemini models to asynchronously analyze conversation histories to extract key facts and user preferences.

这些信息会被持久存储，并按用户 ID 等特定范围进行组织，还会智能更新以整合新数据并解决矛盾。启动新会话时，智能体会通过完整数据回忆或使用嵌入进行相似性搜索来检索相关记忆。此过程使智能体能够在不同会话之间保持连续性，并根据回忆的信息提供个性化响应。

This information is stored persistently, organized by a defined scope like user ID, and intelligently updated to consolidate new data and resolve contradictions. Upon starting a new session, the agent retrieves relevant memories through either a full data recall or a similarity search using embeddings. This process allows an agent to maintain continuity across sessions and personalize responses based on recalled information.

代理的运行程序与首先初始化的 VertexAiMemoryBankService 进行交互。 该服务负责自动存储代理对话过程中生成的记忆。每个记忆都带有唯一的 USER_ID 和 APP_NAME 标签，以确保将来能够准确检索。   

The agent's runner interacts with the VertexAiMemoryBankService, which is initialized first.   This service handles the automatic storage of memories generated during the agent's conversations.   Each memory is tagged with a unique USER_ID and APP_NAME, ensuring accurate retrieval in the future.

from google.adk.memory import VertexAiMemoryBankService agent_engine_id = agent_engine.api_resource.name.split("/")[-1] memory_service = VertexAiMemoryBankService(    project="PROJECT_ID",    location="LOCATION",    agent_engine_id=agent_engine_id ) session = await session_service.get_session(    app_name=app_name,    user_id="USER_ID",    session_id=session.id ) await memory_service.add_session_to_memory(session)

Memory Bank 与 Google ADK 无缝集成，提供开箱即用的体验。 对于其他代理框架（例如 LangGraph 和 CrewAI）的用户，Memory Bank 也通过直接 API 调用提供支持。感兴趣的读者可以在线查看演示这些集成的代码示例。   

Memory Bank offers seamless integration with the Google ADK, providing an immediate out-of-the-box experience.   For users of other agent frameworks, such as LangGraph and CrewAI, Memory Bank also offers support through direct API calls.   Online code examples demonstrating these integrations are readily available for interested readers.

概览

At a Glance

问题 ： 智能体系统需要记住过往交互的信息才能执行复杂任务并提供连贯的用户体验。如果没有记忆机制，智能体就是无状态的，无法维护对话上下文、从经验中学习或为用户提供个性化响应。这从根本上限制了它们只能进行简单的、一次性的交互，无法处理多步骤流程或不断变化的用户需求。核心问题在于如何有效地管理单次对话中即时、临时的信息以及随着时间积累的大量持久知识。

What : Agentic systems need to remember information from past interactions to perform complex tasks and provide coherent experiences. Without a memory mechanism, agents are stateless, unable to maintain conversational context, learn from experience, or personalize responses for users. This fundamentally limits them to simple, one-shot interactions, failing to handle multi-step processes or evolving user needs. The core problem is how to effectively manage both the immediate, temporary information of a single conversation and the vast, persistent knowledge gathered over time.

原因： 标准化的解决方案是实现一个双组件记忆系统，区分短期存储和长期存储。短期上下文记忆保存LLM上下文窗口内的近期交互数据，以维持对话流程。对于必须持久保存的信息，长期记忆解决方案使用外部数据库（通常是向量存储）进行高效的语义检索。诸如Google ADK之类的代理框架提供了用于管理此过程的特定组件，例如用于会话线程的Session和用于临时数据的State。专用的MemoryService用于与长期知识库交互，使代理能够检索相关的历史信息并将其整合到当前上下文中。

Why: The standardized solution is to implement a dual-component memory system that distinguishes between short-term and long-term storage. Short-term, contextual memory holds recent interaction data within the LLM's context window to maintain conversational flow. For information that must persist, long-term memory solutions use external databases, often vector stores, for efficient, semantic retrieval. Agentic frameworks like the Google ADK provide specific components to manage this, such as Session for the conversation thread and State for its temporary data. A dedicated MemoryService is used to interface with the long-term knowledge base, allowing the agent to retrieve and incorporate relevant past information into its current context.

经验法则： 当智能体需要执行的操作不仅仅是回答单个问题时，请使用此模式。对于需要在整个对话过程中保持上下文关联、跟踪多步骤任务进度或通过回忆用户偏好和历史记录来个性化交互的智能体而言，此模式至关重要。每当需要智能体根据过去的成功、失败或新获取的信息进行学习或调整时，都应实施记忆管理。

Rule of thumb: Use this pattern when an agent needs to do more than answer a single question. It is essential for agents that must maintain context throughout a conversation, track progress in multi-step tasks, or personalize interactions by recalling user preferences and history. Implement memory management whenever the agent is expected to learn or adapt based on past successes, failures, or newly acquired information.

可视化摘要

Visual summary

图 1：内存管理设计模式

Fig.1: Memory management design pattern

要点总结

Key Takeaways

快速回顾一下内存管理的要点：

To quickly recap the main points about memory management:

• 记忆对于智能体来说至关重要，它可以帮助智能体跟踪信息、学习和个性化交互。
• Memory is super important for agents to keep track of things, learn, and personalize interactions.
• 对话式人工智能既依赖于短期记忆来获取单次聊天中的即时上下文，也依赖于长期记忆来获取跨多个会话的持久知识。
• Conversational AI relies on both short-term memory for immediate context within a single chat and long-term memory for persistent knowledge across multiple sessions.
• 短期记忆（即时信息）是暂时的，通常受限于 LLM 的上下文窗口或框架传递上下文的方式。
• Short-term memory (the immediate stuff) is temporary, often limited by the LLM's context window or how the framework passes context.
• 长期记忆（能够保留下来的信息）使用矢量数据库等外部存储来保存不同聊天记录中的信息，并通过搜索来访问这些信息。
• Long-term memory (the stuff that sticks around) saves info across different chats using outside storage like vector databases and is accessed by searching.
• 像 ADK 这样的框架具有 Session（聊天线程）、State（临时聊天数据）和 MemoryService（可搜索的长期知识）等特定部分来管理内存。
• Frameworks like ADK have specific parts like Session (the chat thread), State (temporary chat data), and MemoryService (the searchable long-term knowledge) to manage memory.
• ADK 的 SessionService 处理聊天会话的整个生命周期，包括其历史记录（事件）和临时数据（状态）。
• ADK's SessionService handles the whole life of a chat session, including its history (events) and temporary data (state).
• ADK 的 session.state 是一个用于存储临时聊天数据的字典。前缀（user:、app:、temp:）指示数据所属的位置以及是否会保留。
• ADK's session.state is a dictionary for temporary chat data. Prefixes (user:, app:, temp:) tell you where the data belongs and if it sticks around.
• 在 ADK 中，添加事件时，应该使用 EventActions.state_delta 或 output_key 来更新状态，而不是直接更改状态字典。
• In ADK, you should update state by using EventActions.state_delta or output_key when adding events, not by changing the state dictionary directly.
• ADK 的 MemoryService 用于将信息放入长期存储中，供房产经纪人搜索，他们通常会使用工具进行搜索。
• ADK's MemoryService is for putting info into long-term storage and letting agents search it, often using tools.
• LangChain 提供了诸如 ConversationBufferMemory 之类的实用工具，可以自动将单个对话的历史记录注入到提示中，使代理能够回忆起即时上下文。
• LangChain offers practical tools like ConversationBufferMemory to automatically inject the history of a single conversation into a prompt, enabling an agent to recall immediate context.
• LangGraph 通过使用存储来保存和检索语义事实、情景经验，甚至是跨不同用户会话的可更新程序规则，从而实现高级的长期记忆。
• LangGraph enables advanced, long-term memory by using a store to save and retrieve semantic facts, episodic experiences, or even updatable procedural rules across different user sessions.
• Memory Bank 是一项托管服务，它通过自动提取、存储和调用用户特定信息，为代理提供持久的长期记忆，从而在 Google 的 ADK、LangGraph 和 CrewAI 等框架中实现个性化的、连续的对话。
• Memory Bank is a managed service that provides agents with persistent, long-term memory by automatically extracting, storing, and recalling user-specific information to enable personalized, continuous conversations across frameworks like Google's ADK, LangGraph, and CrewAI.

结论

Conclusion

本章  深入探讨了智能体系统中至关重要的内存管理任务，阐述了短暂的上下文信息和长期记忆之间的区别。我们讨论了这些记忆类型的设置方式，以及它们在构建能够记忆信息的智能体中的应用。我们详细了解了 Google ADK 如何提供诸如 Session、State 和 MemoryService 等组件来处理这些任务。  现在我们已经了解了智能体如何记忆短期和长期信息，接下来我们将探讨它们如何学习和适应。下一个模式“学习和适应”指的是智能体如何根据新的经验或数据改变其思维方式、行为方式或知识储备。

This chapter  dove into the really important job of memory management for agent systems, showing the difference between the short-lived context and the knowledge that sticks around for a long time. We talked about how these types of memory are set up and where you see them used in building smarter agents that can remember things. We took a detailed look at how Google ADK gives you specific pieces like Session, State, and MemoryService to handle this.  Now that we've covered how agents can remember things, both short-term and long-term, we can move on to how they can learn and adapt. The next pattern "Learning and Adaptation" is about an agent changing how it thinks, acts, or what it knows, all based on new experiences or data.

参考

References

1. ADK 内存， https://google.github.io/adk-docs/sessions/memory/  
2. ADK Memory, https://google.github.io/adk-docs/sessions/memory/  
3. LangGraph Memory， https://langchain-ai.github.io/langgraph/concepts/memory/  
4. LangGraph Memory, https://langchain-ai.github.io/langgraph/concepts/memory/  
5. Vertex AI 代理引擎内存库， https://cloud.google.com/blog/products/ai-machine-learning/vertex-ai-memory-bank-in-public-preview  
6. Vertex AI Agent Engine Memory Bank, https://cloud.google.com/blog/products/ai-machine-learning/vertex-ai-memory-bank-in-public-preview